office-use

name

office-use

description

Automate live Microsoft Office (PowerPoint, Word, Excel, and Outlook) on Windows via the bundled oxc.exe CLI. Use when a user wants to create, inspect, edit, format, analyze, or organize Office content through an AI agent on Windows, including polished multilingual decks/documents, comprehensive Excel workbook/range/table/chart/pivot automation, and Outlook mail/folder/attachment/calendar/contact/task control. PowerPoint work MUST follow the probe, render, inspect, and fix loop in references/ppt-quality-playbook.md. Outlook outbound mail is draft-only.

office-use

Drive live Microsoft Office applications from an AI agent using the oxc.exe CLI. PowerPoint, Word, Excel, and Outlook are each their own command namespace (oxc ppt …, oxc word …, oxc excel …, oxc outlook …), plus oxc session … for working across multiple open documents.

Hard requirements

• Windows only. The binary uses COM automation and will not run on macOS or Linux.
• Microsoft Office must be installed on the same machine.
• Outlook requires classic Outlook for Windows. New Outlook does not support the Outlook Object Model/COM automation used by oxc.
• The Office application must already be running. Use oxc ppt open --path, oxc word open --path, or oxc excel open --path to open a file in that running instance. If no live instance is found, commands return exit code 3 with error code no_instance.
• Targeting one of several open documents: run oxc session list to see every open document with its 1-based index, then pass --document <index> to a command to act on that document instead of the active one.

Binary location

bin/oxc.exe — the bundled release binary. Production bundles must carry a valid Authenticode signature; use Get-AuthenticodeSignature bin\oxc.exe when provenance matters. See the project README for the build and signing procedure.

JSON output contract

Every command prints a single JSON object to stdout:

{ "ok": true,  "data": { ... }, "error": null }
{ "ok": false, "data": null,   "error": { "code": "...", "message": "...", "hint": "..." } }

Parse this before acting. Never rely on exit code alone without reading the JSON.

Successful generic operations may also include top-level warnings, effects, and next fields. effects reports how many targets matched and changed. Read warnings before continuing and follow the verification steps in next.

Canonical protocol and batches

For compact agent workflows, use get, query, set, remove, batch, render, and watch with canonical paths. Read references/agent-protocol.md before using them.

• Use typed app commands for specialized operations.
• Run mutations with --dry-run first when targeting existing content.
• Keep --max-targets narrow; never broaden it merely to bypass a safety rejection.
• Prefer a batch when several operations target the same application so COM attaches once.
• Request checkpoint: true for material document batches. It creates a recovery copy but is not an atomic rollback guarantee.
• Preserve Outlook's draft-only rule. Generic Outlook mutation never sends mail.

Discover the intended output before authoring

Before creating a new file or substantially restyling one, read references/output-preferences.md and ask the user one compact batch of four to six questions covering the decisions that materially affect the result:

1. Use and audience — live presentation, self-read report, print/PDF, editable working file, dashboard/tracker, or email; and who will read it.
2. Style — for example executive minimal, modern corporate, editorial, technical/data forward, formal/academic, bold/creative, or matched to an existing brand/template.
3. Information density — sparse, balanced, dense report/reference, or a concise main story with a detailed appendix.
4. Color direction — supplied brand colors, light neutral plus accents, dark high-contrast, warm editorial, cool corporate, monochrome, or accessibility-first.
5. Ask only the relevant delivery constraints — language/locale, slide/page size, projection versus print, Office version, accessibility, animation level, and deadline.
6. Ask whether the supplied content is final or whether it should be condensed, reorganized, summarized, charted, or otherwise edited.

Do not repeat choices the user already made, and do not interrupt a narrow edit with unrelated design questions. When answers are optional and the user is unavailable, proceed with the researched defaults in the reference, state the assumptions briefly, and make the file easy to revise. Treat an existing template or brand guide as authoritative.

Exit codes

Code	Meaning
0	Success
2	Bad arguments or validation failure
3	No live Office instance found
4	Target (slide, placeholder, etc.) not found
5	COM failure (Office COM call failed)
6	Unsupported operation

Golden PowerPoint workflow

Follow these steps in order for every slide you create or edit. Do not declare a deck finished until probe is clean AND the rendered image has been visually inspected.

1. List available layouts — run oxc ppt list-layouts and read the returned layout names. Never invent a layout name.
2. Add a slide — run oxc ppt add-slide --layout "<name>" using a name from step 1. Capture the returned slide_id and the full list of placeholders (each has an id and ph_type). Never invent or reuse ids from a previous slide.
3. Choose an authoring mode — use placeholders for theme-led slides; use add-shape, add-textbox, add-picture, add-table, or add-smartart when the message needs a designed composition. Read references/ppt-quality-playbook.md before laying out a deck.
4. Use modern Asian fonts — pass --locale when language is known. For Traditional Chinese use --locale zh-TW (Microsoft JhengHei), not MingLiU. Text commands also infer common scripts when locale is omitted.
5. Probe the slide — run oxc ppt probe-slide --slide <slide_id>. Check every shape in data.shapes: overflows and off_slide must both be false.
6. Render the slide — run oxc ppt render-slide --slide <slide_id> --out slide.png. Open and visually inspect the exported PNG. The render uses PowerPoint's real layout engine and is the authoritative visual truth.
7. Fix and repeat — correct overflow, weak hierarchy, crowding, low contrast, awkward line breaks, and accidental overlaps; probe and render again until clean.

For bordered or filled text, create one add-shape --text ... object; never draw a rectangle and position a separate textbox over it. Set --vertical-align middle and an explicit --margin for short labels. A single-line box must be at least font-size × 1.2 + 2 × margin points high; allow extra room for CJK and inspect the render.

Use the typed PowerPoint commands instead of UI automation whenever possible:

• Start and structure: create, apply-template, set-page-size, list-slides, duplicate-slide, move-slide, set-slide-hidden, and delete-slide.
• Author: add-chart, add-media, add-connector, set-notes, set-hyperlink, set-transition, and set-background, in addition to the core add commands.
• Refine and audit: format-text, transform-shape, delete-shape, probe-slide, render-slide, and export-pdf. Probe output includes z-order, alt text, and decorative state so reading order and accessibility can be reviewed.

Never invent ids

Always read slide_id, placeholder ids, shape ids, and slide dimensions from command output. add-* drawing commands return shp_<id>; use that exact id for styling and animation. Choose geometry deliberately in PowerPoint points and verify it with probe-slide; do not guess an existing object's id.

Golden Excel workflow

For any non-trivial workbook:

1. Run excel inspect, excel list-sheets, and excel used-range before editing.
2. Preserve an existing workbook's conventions. For new workbooks, use one professional font, explicit number formats, deliberate column sizing, a restrained palette, and clear input/formula distinctions.
3. Build with formulas, tables, named ranges, validation, conditional formatting, pivots, and charts where they improve auditability or interpretation. Do not hardcode a value that should remain a formula.
4. Run excel calculate --full-rebuild, then inspect important ranges and formula results. There must be no #REF!, #DIV/0!, #VALUE!, #NAME?, or unintended #N/A.
5. Autofit or explicitly size readable ranges, check for clipped ###, stale placeholders, weak hierarchy, and empty chart sources. For a printable report, run excel export-pdf and inspect the rendered PDF.
6. Save only after the verification pass. Re-run inspection after structural operations such as sheet, table, pivot, or defined-name changes.

Read references/excel.md for the complete command families and QA checklist.

PowerPoint lifecycle cleanup

Determine at the start whether PowerPoint was already running. Never kill POWERPNT.EXE. The CLI releases its COM references after each command; a remaining application is a lifecycle issue, not a reason to terminate a process.

• For a user-owned PowerPoint session, leave the application running and close only a presentation the task explicitly owns.
• For an agent-started session, finish with oxc ppt close --save --quit-if-empty (or --discard only when the user asked to discard). Check quit_performed in the response.
• Run oxc session list before cleanup and target the exact --document index. Never close an unrelated presentation.

Word and Excel lifecycle cleanup

Apply the same ownership rule to Word and Excel. For an agent-started application, finish with word close --save true --quit-if-empty true or excel close --save true --quit-if-empty true. For a user-owned application, target only the task-owned document/workbook and pass --quit-if-empty false. Never kill WINWORD.EXE or EXCEL.EXE; verify the returned application_quit value. If an agent-owned launch created an extra blank startup file, retry with --quit-application; this discards remaining startup files and must never be used against a user-owned session.

Outlook safety and targeting

• Outbound messages are draft-only. draft, reply-draft, and forward-draft save an Outlook item for human review; the CLI exposes no send command.
• Prefer stable entry_id, folder_id, and store_id values returned by list/read commands. Folder names and message indices are convenience selectors and can change.
• Read before mutating. List the relevant folder/items, capture stable IDs, then update, move, save attachments, or delete only the intended item.
• Calendar appointments, contacts, and tasks support list/create/update; delete-item is the explicit destructive operation for any item selected by EntryID.
• Outlook date/time strings are interpreted by the installed local Outlook instance. Prefer an unambiguous local ISO-like form such as 2026-07-24 10:00.

References

• references/output-preferences.md — required discovery questions, common style and density choices, artifact-specific options, and safe defaults for new Office outputs.
• references/powerpoint.md — PowerPoint command catalog, including shapes, text boxes, pictures, tables, SmartArt, styling, and animation.
• references/ppt-capability-matrix.md — audited coverage of safe PowerPoint object-model families and explicit exclusions. Read this before falling back to UI automation or declaring a capability unavailable.
• references/ppt-quality-playbook.md — mandatory quality loop and researched design rules for presentation and report decks. Read this before authoring or finishing any deck.
• references/word.md — Word command catalog and locale-aware typography rules.
• references/excel.md — Excel command catalog and quality loop: workbook/sheet/range formatting, formulas, filters, tables, names, charts, validation, conditional formatting, pictures, pivots, recalculation, protection, and PDF export.
• references/outlook.md — Outlook command catalog: draft-only outbound mail plus stores/accounts, folders, messages, attachments, calendar, contacts, and tasks.
• references/word-excel-outlook-capability-matrix.md — audited coverage and explicit exclusions for the Word, Excel, and classic Outlook object models.
• references/peer-project-findings.md — design and agent-workflow principles adapted from Open Design, Open Slide/slides-grab, and OfficeCLI.
• references/session.md — session list and --document targeting across multiple open documents.

The complete machine-readable catalog (all namespaces and args) is always available via oxc schema.

Troubleshooting

Symptom	Cause	Fix
Exit 3, code no_instance	No live PowerPoint instance	Open the deck in PowerPoint first, then retry
Exit 4, code not_found	Slide or placeholder id is stale or wrong	Re-run list-layouts / add-slide / probe-slide to get current valid ids
Exit 2	Bad argument (wrong flag, missing value, invalid path)	Check the command syntax in references/powerpoint.md
Exit 5	COM call failed inside Office	Verify Office is responsive; try saving the deck and retrying
POWERPNT.EXE remains after an agent-owned task	The presentation/application was not closed	Target the task-owned deck and run ppt close --save --quit-if-empty; never kill the process
WINWORD.EXE or EXCEL.EXE remains after an agent-owned task	The last task-owned file was saved but not closed	Run the matching close --save true --quit-if-empty true; never kill the process