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
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.
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
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.
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.
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.
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.
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.
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.
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.
Public sources
Where to check each statement, in the public repositories.