Sidecar protocol

atomic-agent serve is how a network client drives the agent. The sidecar is how a desktop app embeds it: you spawn atomic-agent-sidecar as a child process and talk to it over its own stdin and stdout, with no port, no bearer token, and no HTTP stack in between.

That is the shape a Tauri or Electron host wants. The agent runs as a child of your app, dies with it, and streams its whole event feed — steps, tool calls, reasoning deltas, approval requests, logs, metrics — back up the pipe as it happens.

atomic-agent-sidecar

It takes no flags. Configuration comes from the usual config.json and ATOMIC_AGENT_* environment variables, resolved at boot exactly as they are for the CLI.

Developer Preview

Atomic Agent is a Developer Preview. Request types, event names, and payload shapes still move between releases. Pin a release if you build a host against this protocol.

The envelope

Every frame in both directions is one JSON object on one line, terminated by \n. No length prefixes, no framing beyond the newline. A line that fails to parse does not kill the process — it comes back as an error event.

There are exactly three kinds of frame, distinguished by kind:

kind	Direction	Meaning
request	host → sidecar	Ask the agent to do something. Carries id, type, payload.
event	sidecar → host	Unsolicited notification. Carries id, type, payload, optional correlationId.
response	sidecar → host	Exactly one per request. Carries id, correlationId, ok, payload, optional error.

correlationId on a response is the request’s id — that is how you match a reply to what you asked. Every frame also carries its own fresh id (a UUID).

Request

{"kind":"request","id":"a1b2","type":"send_message","payload":{"sessionId":"s-9f3","text":"List the TypeScript files here"}}

Event

{"kind":"event","id":"e77c","type":"tool_call_started","payload":{"sessionId":"s-9f3","stepIndex":-1,"tool":"fs.list","args":{"path":"."}}}

Response

{"kind":"response","id":"r04e","correlationId":"a1b2","ok":true,"payload":{"reason":"reply","turnCount":1,"stepCount":3}}

Events and responses interleave freely on stdout. A single send_message typically emits dozens of events before its one response lands, so a host must read the stream continuously rather than blocking on the reply.

Requests

type	Payload	Response payload
ping	—	{ ok, llamaUrl, stateDir, version }
start_session	{ workingDir, metadata? }	{ sessionId }
send_message	{ sessionId, text, maxSteps? }	{ reason, turnCount, stepCount }
cancel	{ sessionId }	{ cancelled }
approval_response	{ approvalId, approved, reason? }	{ resolved }
get_session	{ sessionId }	The SessionState object, or null
skill_install	{ sourcePath, force? }	{ name, installedAt }
skill_uninstall	{ name }	{ removed }
skill_list	—	{ skills: [{ name, version, description, source }] }
shutdown	—	{ ok: true }

A few behaviours that are not obvious from the table:

• One session at a time. The sidecar process hosts exactly one active session. A second start_session disposes the first — aborting its turn and shutting down its runtime — before building the new one. If your app needs concurrent sessions, spawn a sidecar per session or use serve instead.
• send_message serialises per session. Two rapid messages on the same session queue through the turn controller FIFO rather than racing.
• cancel and get_session are scoped to the active session. cancel on any other id returns { cancelled: false } rather than an error. get_session falls back to reading SQLite for a non-active id, but only while a runtime exists — otherwise it returns null.
• Skills need a session. skill_install and skill_uninstall throw when no session is active; skill_list returns an empty list instead.

run_step is declared but not handled

run_step appears in the HostRequestType union, but no handler is registered for it. Sending one gets you a failed response with code unknown_request. Drive turns with send_message.

Events

Everything the agent does surfaces as an event. Hosts typically render the first group, log the middle group, and gate on approval_request.

Turn and step

type	Payload
session_started	{ sessionId, workingDir }
turn_started	{ sessionId, turnIndex }
turn_finished	{ sessionId, turnIndex, reason, stepCount, durationMs }
step_started	{ sessionId, stepIndex }
step_finished	{ sessionId, stepIndex, tokensUsed, durationMs }
session_completed	{ sessionId, reason }
session_failed	{ sessionId, error, category }

turn_finished.reason is one of reply, finish, max_steps, cancelled, failed.

Content

type	Payload
user_message	{ sessionId, text }
assistant_delta	{ sessionId, text }
assistant_reply	{ sessionId, text }
reasoning_delta	{ sessionId, stepIndex, text }
tool_call_started	{ sessionId, stepIndex, tool, args, batchIndex?, batchSize? }
tool_call_result	{ sessionId, stepIndex, tool, status, summary, truncated?, batchIndex?, batchSize? }

Several assistant_delta events stream the reply as it is generated, followed by one terminal assistant_reply carrying the full text. A host that renders deltas live must ignore the final body or diff it against its own buffer, or the reply appears twice.

batchIndex / batchSize are present only when a step emitted more than one parallel tool call. Solo calls omit both.

Approvals and system

type	Payload
approval_request	{ approvalId, sessionId, tool, category?, reason, preview?, affectedResources? }
llm_request	{ sessionId, slotId, promptTokens, cacheReused }
llm_response	{ sessionId, completionTokens, durationMs }
llm_unavailable	{ url, error, mode, hint }
skill_registry_updated	{ installed: [{ name, source }] }
log	{ level, message, context? }
metric	{ name, value, tags? }
error	{ message, code?, stack? }

approval_request is the one event a host must handle: the turn is blocked until you answer with an approval_response request carrying the same approvalId. category tells you why the gate fired (shell, fs_write_home, trust_config, …) so you can render something better than the tool name.

llm_unavailable fires at start_session when llama-server is unreachable. It is informational — the session is still created — and hint carries the actionable next step.

stepIndex is -1 on tool events

tool_call_started and tool_call_result are forwarded with stepIndex: -1 rather than the real step number. Correlate tool calls with steps using the surrounding step_started / step_finished events instead of this field.

The SidecarEventType union also declares pong and trace. Nothing emits them today — ping answers with a normal response, not a pong event.

Errors

A failed request still produces exactly one response, with ok: false and a populated error:

{"kind":"response","id":"r91a","correlationId":"a1b2","ok":false,"payload":{},"error":{"message":"no active session with id s-000","code":"handler_failed"}}

code	When
unknown_request	No handler registered for that type (including run_step).
handler_failed	The handler threw. The message is the thrown Error.message.
parse_error	A stdin line was not valid JSON. Emitted as an event, not a response — an unparseable line has no id to correlate against.

A handler_failed response is always accompanied by an error event carrying the same message plus a stack trace. For parse_error, the offending raw line is placed in the event’s stack field.

No handler failure kills the sidecar. Every route is wrapped, so a bad request degrades to one error frame and the process keeps serving.

ping reports a hardcoded version — do not negotiate on it

The ping handler returns version: "0.1.0", a literal string baked into the source. The package is 0.2.1, and this field has not tracked it. It is not the sidecar’s real version and it will not change when you upgrade.

Do not build capability or version negotiation on it. Treat ping purely as a liveness probe (ok, plus llamaUrl and stateDir for diagnostics), and pin the sidecar release you built against instead.

A minimal session

The typical host lifecycle, start to finish:

1. Spawn atomic-agent-sidecar; attach line-buffered readers to stdout.
2. Send ping to confirm the process is alive and see which llama-server it resolved.
3. Send start_session with the workingDir the tools should resolve against. Keep the returned sessionId.
4. Send send_message. Render assistant_delta as it streams, answer any approval_request with approval_response, and wait for the response frame.
5. Send cancel if the user interrupts.
6. Send shutdown before exiting, so the runtime closes its databases cleanly.

host → {"kind":"request","id":"1","type":"ping","payload":{}}
     ← {"kind":"response","id":"…","correlationId":"1","ok":true,"payload":{"ok":true,…}}
host → {"kind":"request","id":"2","type":"start_session","payload":{"workingDir":"/Users/you/project"}}
     ← {"kind":"event","id":"…","type":"session_started","payload":{"sessionId":"s-9f3",…}}
     ← {"kind":"response","id":"…","correlationId":"2","ok":true,"payload":{"sessionId":"s-9f3"}}
host → {"kind":"request","id":"3","type":"send_message","payload":{"sessionId":"s-9f3","text":"…"}}
     ← {"kind":"event",…,"type":"turn_started",…}
     ← {"kind":"event",…,"type":"assistant_delta",…}      ← many
     ← {"kind":"event",…,"type":"assistant_reply",…}
     ← {"kind":"response","id":"…","correlationId":"3","ok":true,"payload":{"reason":"reply",…}}

The types ship with the package

sidecar-events.ts is the single source of truth for this protocol and is exported from the package root. A host written in TypeScript can import HostRequest, SidecarEvent, SidecarResponse, and every payload interface directly rather than hand-writing them.

Related

HTTP server

serve — the same runtime behind an OpenAI-compatible API, when a port suits you better than a pipe.

Approval gates

What approval_request is asking, and which categories can fire.

Architecture

How the runtime, turn controller, and agent loop sit behind both front ends.

Traces and replay

Recording a session for later inspection.