RPC Mode

September 20, 2026 · View on GitHub

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 using AgentSession 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.

Not sure RPC is the right integration mode? Compare it with the SDK and JSON mode on Programmatic use.

Starting RPC Mode

atomic --mode rpc [options]

Common options:

--provider <name>: Set the LLM provider (anthropic, openai, google, etc.)
--model <pattern>: Model pattern or ID (supports provider/id and 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

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

All commands support an optional 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 \n only
Accept optional \r\n input by stripping a trailing \r
Do not use generic line readers that treat Unicode separators as newlines

In particular, Node readline is not protocol-compliant for RPC mode because it also splits on U+2028 and U+2029, which are valid inside JSON strings.

import subprocess
import json

proc = subprocess.Popen(
    ["atomic", "--mode", "rpc", "--no-session"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True
)

def send(cmd):
    proc.stdin.write(json.dumps(cmd) + "\n")
    proc.stdin.flush()

def read_events():
    for line in proc.stdout:
        yield json.loads(line)

# Send prompt
send({"type": "prompt", "message": "Hello!"})

# Process events
for event in read_events():
    if event.get("type") == "message_update":
        delta = event.get("assistantMessageEvent", {})
        if delta.get("type") == "text_delta":
            print(delta["delta"], end="", flush=True)
    
    if event.get("type") == "agent_end":
        print()
        break

Example: Interactive Client (Node.js)

Moved to RPC client examples.