IPC methods

Declared in packages/shared/src/ipc/protocol.ts; handled in apps/core/src/server.ts. For how the transport works — the two kinds of line sharing one pipe, why streaming is out of band — read the IPC protocol. This page is the listing.

All 71 implemented methods are declared in METHODS. The ✓ column marks that shared compile-time contract. Required fields also have a runtime contract in REQUIRED_PARAMS; the server checks it before dispatch.

Errors

-32602 names the missing or mistyped required field. Validation is deliberately narrow: optional and unknown fields remain the handler’s responsibility for forward compatibility. A line that fails to parse on stdin is logged to stderr and dropped — it has no id to answer.

Tools

tools.call runs a tool directly, outside the agent loop and outside the permission engine, with cwd = process.cwd().

Session lifecycle

Notes that bite people:

• session.start silently falls back to process.cwd() when projectPath is missing or does not exist.
• session.send is the long call. If a turn is already running for that session the prompt is queued, not raced, and the call resolves immediately with { queued: true, id } plus a message_queued event. Queuing a message with images throws instead — dropping them silently would be data loss.
• session.stop aborts the turn, not the session. The mapping is kept so the conversation stays continuable after Ctrl+C.
• session.resume seeds provider and model from config.json when the stored session has none, and throws if neither has one.
• session.delete disposes six per-session caches. It is the only place that does, which is why ending a session any other way leaks them.
• session.list never carries transcripts. The handler’s type says SessionContext[], but messages is hard-coded to [] (manager.list()), so the declared SessionMeta[] is the honest shape. Use session.resume to get messages.

Session tree and rewind

Navigation changes the conversation leaf only. Rewind can restore the associated shadow-git snapshot first; the optional flags let a caller request either half. Both refuse to race a running turn.

Session transfer

Claude Code import

Read-only: core never writes to $CLAUDE_CONFIG_DIR.

Providers and models

hasApiKey is the whole reason providers.list is shaped this way — the key itself never crosses the pipe.

Config

config.get returns the file with every secret replaced by whether it is set: each provider entry becomes { hasApiKey, model?, authMode? } and each web entry { hasCredential }. current, lastAgentMode and recovery pass through unchanged. The redaction is an allowlist built field by field, not a blocklist of known secret names, so a credential field added later is excluded by default rather than leaked until someone remembers it.

That matters because the same method is reachable over the web transport’s POST /api, whose host is a parameter — a backend bound to 0.0.0.0 would otherwise hand out API keys.

Memory

projectPath defaults to process.cwd() everywhere here. memory.query routes through the graph service (semantic top-k, then a graph walk), falling back to the keyword scorer when embeddings are unavailable. Note the odd one out: graph.explore is the only memory method not under the memory. prefix, and it ignores projectPath entirely.

Prompts

decision is one of allow-once, allow-session, allow-project, allow-always, deny. The last two write a rule into settings.json (project and user scope respectively). Answering a request that someone else already answered returns -32002, not a generic failure — with two frontends watching one session, losing the race is state, not an error.

Unanswered prompts time out after 30 minutes, and a timeout resolves to deny. If no frontend is listening at all, the ask is rejected immediately — headless never means silent allow.

Background work

Both output methods are positional reads. Opening a frontend panel does not advance the cursor used by the model.

Extensions

Reload re-imports extension files and re-registers their tools, commands and hooks. This is process-wide rather than scoped to one session.

Everything else

The night.* methods only read what a separate freecode night process left on disk; they boot none of the backend, and the daemon never runs a night itself.

Stream events

Emitted during session.send, one JSON object per line, no JSON-RPC envelope. sessionId is stamped by the bus bridge on every variant; a client driving one session can ignore it, a client multiplexing several cannot.

Two rendering rules worth encoding once in a client:

• text and text_delta are not additive. On the streaming path you get the deltas and a final text snapshot; concatenating both duplicates the turn.
• memory_saved arrives after done. Extraction is fire-and-forget, so treat it as an out-of-band notice rather than part of the turn.

totalInputTokens already includes cache writes — totalCacheWriteTokens is the same tokens broken out for the hit-rate display, so summing them double-counts.

The older StreamResponse union (text / code / tool / done / error) still exists in protocol.ts for backward compatibility. Prefer StreamEvent.

Known gaps

Also tracked in TODO.md and shared with the IPC internals page.

• graph.explore breaks the naming convention and hard-codes process.cwd() while every neighbouring memory method takes projectPath. It should be memory.graph.explore with the same parameter.