Automation & AI Agents

Certum Draft has a local automation API that lets AI assistants and scripts do real work through the app — reading matters and correspondence, scanning and rendering documents, drafting invoice lines, filing notes, proposing field values and tasks — with the app’s own rules (locks, numbering, drafts, the audit log) enforced on every call. It is built on one principle: the machine drafts, the solicitor decides.

Everything runs on your Mac. There is no cloud service, no account, and nothing listening on the network — the API is a Unix socket that only processes running as you, on your Mac, can reach.

Turning it on

Settings → Automation has two switches, deliberately separate:

Enable local automation API — persists across launches and starts the socket. While it’s on, Horace’s silhouette shows in the menu bar and any tool running as your user on this Mac can read matter data.
Allow automation writes — session-scoped: it resets every time Certum Draft quits, so write access is a fresh decision each session, never ambient. It covers every write: proposals, renders, file notes, institutions, checklists, tasks, grants, Notion links and invoice lines. A small bolt on the menu-bar glyph means writes are on.

Every request — reads included, and writes refused because the switch was off — is appended to an audit log (automation-audit.jsonl, revealable from the Settings pane), with the calling tool’s name and, for writes, the full payload.

What agents can do today

Read — search matters; get a matter’s details, fields, documents, correspondence and calendar; read files one at a time or twenty in a call (file.read extracts PDFs, Word documents and filed .eml emails — headers, the plain-text body and attachment names); list upcoming key dates across the practice; read the invoice register and firm accounts; look up the estates institution catalogue; read a matter’s tasks (matter.tasks), the firm’s people a task can be for (tasks.people) and the matter’s checklist with each item’s tick state and provenance (matter.checklist); ask what became of a proposal batch (matter.proposals.status — pending, accepted, rejected or withdrawn, and by whom).

Work with documents — scan a template for its placeholders, and render documents through the same engine the document wizard uses, into the matter’s own folders. A render result says whether each document came out complete, what it flagged, and whether the engine fell back because a precedent could not be parsed (fallback, with its warnings) — a fallback render is never reported as complete.

Draft, for your approval — the writes are shaped so a human decision sits between the agent and the record:

Field proposals never touch the matter directly. matter.propose_fields files a pending proposal batch; the values wait in the matter’s review sheet for the solicitor to accept, edit or reject one by one. A key that is one or two letters from a field in the matter’s pack — a likely typo — refuses the whole batch and names the field; a key the pack doesn’t declare at all is staged but flagged “not in pack” for the reviewer.
Institutions can be proposed (matter.institutions.propose stages asset holders for review, each with a note saying where the agent found it) or, for tools you trust more, added and updated directly: lifecycle dates, a contact logged (an email, call, portal lodgement or form — the same entry the Contact Log composer makes, which moves the chase clock and any tracked follow-up task), a file closed without funds, and grants recorded.
Tasks can be created (matter.task.add). A task for this Mac’s own user is queued and appears in Notion about half a minute later. A task for anyone else is held on the matter as a proposed task: nothing reaches Notion or the colleague until the person whose Mac proposed it accepts it in the review sheet, where the title, assignee and due date can be changed first. office: true files a task to the firm’s Office page instead of a matter, for this Mac’s own user only; an Office task for a colleague is refused. Each call carries a request_id, so a retry returns the task’s state rather than making a second one. Tasks can also be completed (matter.task.done), through the same path as a tick in the app — the lists, the 9am reminder and the notice to whoever assigned it. It refuses a task that tracks an institution follow-up (log the chase with matter.institutions.log_contact instead) and a repeating task (only a person can say which period a tick meant).
Invoice lines append to the matter’s invoice draft (idempotent, so an agent retry can’t double-bill), and the solicitor reviews the draft before any bill is generated.
File notes are filed as PDFs into Correspondence via the same engine as the File Note button, optionally backdated to when the attendance happened — see File Notes.
Checklist items can be ticked, unticked, or marked not-applicable (matter.checklist.update) with exactly the workspace’s semantics — the audit log records who, and the item’s provenance shows the API client’s name.

Deliberately absent: there is no matter.create. Opening a file is a professional decision with intake, conflict and identity obligations attached — matter creation stays with the humans, and the API’s jurisdiction begins after the wizard.

Reviewing what an agent proposed

Proposals are visible firm-wide. The dashboard’s Proposals to Review card, a Proposals column and filter in the Matters table, and the menu-bar item each list every matter with values or tasks waiting; a row opens the matter with its review sheet already up. Proposals staged before a relaunch, or on another Mac, show up too.

The review sheet is a desk, not a confirm button. Each row shows the field’s label, block and stage from the pack, grouped in pack order, with the agent’s value beside the current one. You can edit a value before accepting it — Yes/No fields and fixed choices use pickers, dates and amounts are checked and stored in the app’s format. Chips flag values you typed, fields that changed since the proposal was made, hidden and computed fields, keys this pack doesn’t have, and fields that would rename the matter folder. Accept N into Empty Fields takes everything safe in one go and leaves anything risky — a field you changed since the proposal, or one gated by another value in the same batch — for you to decide row by row. ⌘↩ accepts and ⌘⌫ rejects the highlighted row. Proposed tasks sit in their own section of the sheet, never part of a bulk accept. Every decision is recorded in the matter’s review log, which is what matter.proposals.status reads.

Connecting an AI assistant

The API speaks MCP (the Model Context Protocol). The bridge ships inside the app, with the Python it runs on, so Claude Code — or any MCP host — connects with one command and nothing else installed:

claude mcp add certum -- \
  "/Applications/Certum Draft.app/Contents/Resources/PythonRuntime/python/bin/python3" -I -B \
  "/Applications/Certum Draft.app/Contents/Resources/certum-mcp"

The bridge discovers the op list from the app at connect time, so as the API grows, new tools appear automatically. Read tools are marked read-only to the host; write tools are labelled [WRITE] and carry honest retry hints — the app declares per operation whether a retry is safe (api.hello carries idempotent and destructive for every op). A file note is a new PDF every time, and a render with overwrite re-renders every time; everything else replays safely. It speaks both the current MCP revision (2026-07-28) and the earlier handshake-based ones, and a session started before Certum was running picks up the tools once the app answers.

Point each host at the copy inside the app rather than one of your own: it updates with the app, it reports its version when it connects, and Settings → Automation lists the bridges seen this session with a warning for an out-of-date one, which can mark writes as safe to retry when they aren’t.

Scripts can skip MCP and speak to the socket directly — newline-delimited JSON, one request per line. The socket path and protocol are documented in the repository’s docs/AUTOMATION_API.md.

How writes land

A write’s ok means the change reached disk, not that it was accepted for later. On a matter that is open in Certum, the write goes through the open workspace and is saved with it; on a matter that isn’t open, writes to the matter file queue one at a time per matter and take the editing lock in turn, so two agents (or an agent and a chase logged from a ticked task) can’t drop each other’s change. document.render writes no matter file and stays out of the queue; it is refused while the matter’s lock is held. Opening a matter waits for its queued writes first, so a burst of agent writes to one matter can delay opening it for a moment. A matter locked on another Mac refuses writes with matter_locked rather than guessing.

Where this is heading

The surface today covers reading, document work, proposals for fields, institutions and tasks, invoice drafting, notes and the estates register. The goal is a comprehensive agentic API over the whole matter lifecycle — an assistant that can prepare the next step on any matter and hand it to you for the decision — with every extension keeping the same three properties: local, audited, and human-approved.

Tasks — where agent-created and proposed tasks appear
File Notes — the note engine the API shares
Invoices — where API-drafted lines land for review
Institutions — the estates lifecycle the API can drive
Settings — the Automation pane