Skip to content

Docs · Internals

Where Claude Code ends and any agent begins

The nexus SDK started as a Claude Code client. This diagram draws the line between what any agent has to provide and what belongs to Claude Code, and shows the fake CLI that makes the contract executable.

What it does

Any agent provides turns, text and thinking, tool calls and results, a token stream, a result with cost and usage, permission requests, interrupts and nested sub-agents.

Claude Code adds its own command line, a stream-json protocol, a control channel with an initialize handshake, and hooks.

The neutral agent contract and the providers are built on top of this surface, so a new agent does not have to imitate Claude protocol.

The diagram

The boundary between generic agents and Claude Code in the SDKFlow diagram. The backend imports the SDK public surface: clients, types and the Transport trait. Types carry the generic part. The Transport leads to the Claude-specific part: the command line, the routing of stdout between control messages and conversation messages, the control protocol and the hooks, which talk to the claude process. The Transport trait is the seam: it is nearly generic but leaks protocol details, and it is only used with a fake transport in tests. A fake_claude executable simulates the claude process and specifies the contract. The generic part and the seam point to the agent module and providers built on top.simulatesto closebackend: ChatManagerimports the SDKclientsInteractiveClient, Query, ...typesMessage, ContentBlock, StreamEventData,ClaudeCodeOptions, PermissionModetransporttrait Transport, SubprocessTransport,MockTransportGeneric: what any agent providesuser turn, text and thinking, tool use and result,token stream, result with cost and usage,permission request and answer, interrupt,nested sub-agentscommand line: stream-json in and out,permission mode, inline MCP config, resumefind the binary, check the version(warns only)stdout routingcontrol messages vs conversation messagescontrol protocol: initialize handshake,can_use_tool, hook_callback,set_permission_mode, set_modelhooks: PreToolUse, PostToolUse, UserPromptSubmit,Stop, SubagentStop, PreCompactThe seam: trait Transportalmost generic, but leaks the protocol(raw JSON control, stdin sender, child pid)used with a fake transport in tests onlyfake_claudethe executable specification of the contractscripted by environment variablesused by the integration testsclaude processagent module + providers/neutral contract on top of all this

Drag to move. Pinch, Ctrl + wheel or the + and - keys to zoom; arrow keys to move; 0 to fit; double-click to fit. Select a node to light up its links.

Zoom outZoom inFull screen
Redrawn from the verified diagram nexus-sdk-provider-boundary (verified 2026-10-05). Labels are the names used in the code.
Text description of the diagram

Flow diagram. The backend imports the SDK public surface: clients, types and the Transport trait. Types carry the generic part. The Transport leads to the Claude-specific part: the command line, the routing of stdout between control messages and conversation messages, the control protocol and the hooks, which talk to the claude process. The Transport trait is the seam: it is nearly generic but leaks protocol details, and it is only used with a fake transport in tests. A fake_claude executable simulates the claude process and specifies the contract. The generic part and the seam point to the agent module and providers built on top.

Guided reading

  1. Step 1. The public surface

    The backend sees clients (such as InteractiveClient), types (Message, ContentBlock, PermissionMode and others) and the Transport trait with its subprocess and mock implementations.

  2. Step 2. The generic part

    User turn, text and thinking, tool use and tool result, token stream, result with cost and usage, permission request and answer, interrupt, nested sub-agents. These are the things the neutral contract generalises.

  3. Step 3. The Claude Code command line

    The SDK builds the claude command with stream-json input and output, a permission mode, an inline MCP configuration and resume. It finds the binary and checks its version, which only warns.

  4. Step 4. Routing what the process prints

    Lines from stdout are routed: control messages go to the control channel, everything else to the message parser.

  5. Step 5. Control protocol and hooks

    The control channel carries the initialize handshake, can_use_tool, hook_callback, set_permission_mode and set_model. Hooks are PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop and PreCompact.

  6. Step 6. The seam

    The Transport trait is almost generic but leaks the protocol: raw JSON control messages, a raw stdin sender, a child process id. In production it is used with one transport only; a second one exists only in tests.

  7. Step 7. The fake CLI

    fake_claude is driven by environment variables and directives (emit, reply_control, wait_eof and others). Tests across the crate use it to run the real protocol without the real CLI.

Why it is built this way

An executable specification

The fake CLI is the part of the contract that runs. A new provider delivers one first, before transport code.

Name the leaks

The diagram records where the generic seam still depends on Claude details, so closing them is a visible task rather than a surprise.

Additive evolution

Nothing public is removed while the backend depends on it. The neutral module grows beside the older client, and the older types are wrapped rather than replaced.

What is not established

  • Known debts when the diagram was last checked (2026-10-05): two wire forms of the interrupt request coexist, and the claude command line is built in five places across the SDK and the API crate.