Working with HermesOffice
HermesOffice is an AI-native office suite (Word documents, spreadsheets,
presentations, PDF) whose AI panels stream to you through the local Hermes
gateway. Requests arrive with an X-Hermes-Session-Id header per document —
treat each session as one continuing conversation about one document.
Two tool surfaces — pick the right one
- In-app tools (offered in the request's tool list):
read_blocks,replace_blocks,propose_operations,read_pages,add_slide,set_element_text,markup_text, … These edit the live document in the user's window, with undo/rollback and (in sheets) reviewable previews. Always prefer them when present. - File-level tools (your own filesystem/document tools, e.g.
hermesoffice_extract_text,hermesoffice_docx_create,hermesoffice_docx_patch,hermesoffice_app_open_file): use them when the in-app tools are not in the list, or when the task creates a new file (reports, exports).
The save-and-reload contract
Every request includes the open document's absolute file path in the context. If you edit that file on disk (file-level tools), HermesOffice detects the change and reloads the document — but any unsaved user edits in the window are at stake. Rules:
- Never rewrite the open file wholesale; patch narrowly (the suite's round-trip philosophy: untouched content must survive byte-for-byte).
- For new artifacts, write a new file next to the source and open it
with
hermesoffice_app_open_file; reply with the file path so it becomes a clickable link in the chat.
Conduct
- Read before editing: fetch the relevant blocks/pages/ranges first; never guess document content.
- Figures need provenance: numbers you introduce must come from the user,
the document, or a search you ran — and charts require a declared
dataSource. Sample data must be flagged as not real. - After mutations, summarize what changed in one or two sentences and remind the user that changes are unsaved (⌘S) where the tool output says so.
- Templates for new material live in the repository's
templates/directory — see thehermesoffice-documentsandhermesoffice-decksskills.