RPC Mode
RPC mode enables headless operation of the coding agent via a JSON protocol over stdin/stdout. This is useful for embedding the agent in other applications, IDEs, or custom UIs. Note for Node.js/TypeScript users: If you’re building a Node.js application, consider usingAgentSession directly from @bastani/atomic instead of spawning a subprocess. See src/core/agent-session.ts for the API. For a subprocess-based TypeScript client, see src/modes/rpc/rpc-client.ts.
Where to go next
This page starts RPC mode and walks one client end to end. The rest is split by job:- RPC protocol — every command, event, type, and error contract.
- RPC extension UI protocol — drive extension-rendered UI over RPC.
- RPC client examples — additional client implementations.
- Stored summaries and workflow history — read session and workflow summaries without starting a model turn.
Starting RPC Mode
--provider <name>: Set the LLM provider (anthropic, openai, google, etc.)--model <pattern>: Model pattern or ID (supportsprovider/idand optional:<thinking>)--name <name>/-n <name>: Set the session display name at startup--no-session: Disable session persistence--session-dir <path>: Custom session storage directory--storage '<json>'/--storage-file <path>: Select storage for this process’s sessions and workflow runs
ATOMIC_STORAGE (or --storage) holding the same JSON selection as the shared storage setting, for example an adapter selection with secrets read from { "env": ... }. The child keeps its sessions and workflow runs there, and list_sessions and list_workflow_runs report that store. An atomic started without the selection keeps using its settings. An invalid selection fails at startup with StorageConfigError naming the variable or flag. See Selecting storage per process.
Protocol Overview
- Commands: JSON objects sent to stdin, one per line
- Responses: JSON objects with
type: "response"indicating command success/failure - Events: Agent events streamed to stdout as JSON lines
id field for request/response correlation. If provided, the corresponding response will include the same id.
A complete saved provider/model default can block prompts if its provider remains unsupported after registration. The process stays live, but prompt returns a correlated error with the generic configuration diagnostic before emitting any user/model event. get_available_models and other non-prompt commands remain available.
Clear this condition with a successful explicit set_model or a successful cycle_model that returns a different available model. A null or unchanged cycle result does not clear it. Replacing the session applies the new session’s condition again.
Supported providers with an unknown model or missing authentication retain ordinary automatic fallback behavior.
Framing
RPC mode uses strict JSONL semantics with LF (\n) as the only record delimiter.
Atomic does not impose a size limit on RPC or isolated interactive-engine JSONL records. Commands, responses, events, and render frames are serialized in full. Clients and extensions must account for the memory and latency cost of large records and must not add a smaller line limit unless they intend to reject valid Atomic output.
This matters for clients:
- Split records on
\nonly - Accept optional
\r\ninput by stripping a trailing\r - Do not use generic line readers that treat Unicode separators as newlines
readline is not protocol-compliant for RPC mode because it also splits on U+2028 and U+2029, which are valid inside JSON strings.