office-use

# 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: ```json { "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 |