Connect a local client
Use magi-code serve --stdio to run an owned local-agent process over Unix pipes. The backend handles models, tools, approvals, and durable history. Your client handles drafts and display.
Start the backend
- Configure providers, enabled models, and MCP approvals through Mission Control.
- Launch an absolute path to the installed binary with arguments
serve --stdio. - Set the working directory explicitly. Let
MC_HOMEselect storage independently. - Provide stdin/stdout pipes and drain stderr separately. Do not use a TTY, regular file, or socketpair as a protocol endpoint.
- Send
initializewith the capabilities your client requires.
Readiness confirms local configuration, not remote provider availability. Initialization may start approved MCP servers. Never copy credentials into the client or fall back to client-side provider calls.
Keep state distinct
- Admission is not proof that input was saved. Save a relaunch session ID only after a durable acknowledgement.
- Replace deltas with complete
message.reconcileparts. A completed message is not a completed run. - Wait for
run.finishedbefore another turn or history request. Use its history revision. - Scope transient IDs to the child process. Reopen only an acknowledged durable session ID after restart.
- Do not replay uncertain requests. Inspect history explicitly after lost output or process failure.
Stop safely
Request cancellation, keep draining output, then wait for terminal accounting. On application exit, close input and give the child a bounded time to finish before terminating and reaping it. Cancellation does not undo completed effects.
See the protocol for exact frames, limits, and errors, session discovery, and model selection.
Historical evidence
Archived handoff and integrated acceptance preserves pinned revisions and captured traces. They are examples from those revisions, not proof of current runtime coverage.