Claude Code Adapter Deep Dive

How the adapter spawns the claude CLI as a child process, passes task context via stdin/args, captures stdout, maps exit codes to run status, and handles token reporting.

The Claude Code Adapter In Depth

What you'll learn

How the claude-code adapter works internally, its configuration options, error handling, and how to debug it when things go wrong.

How It Works

The claude-code adapter spawns a child process that runs the claude CLI:

const proc = spawn('claude', [
  '--model', config.model,
  '--max-tokens', String(config.max_tokens),
  '--output-format', 'json',
], {
  input: fullPrompt,  // system + task prompt piped to stdin
  timeout: config.timeout_ms ?? 60_000,
  env: { ...process.env, ANTHROPIC_API_KEY: config.api_key ?? process.env.ANTHROPIC_API_KEY }
});

The output is captured from stdout and parsed as JSON. The claude CLI's --output-format json flag returns a structured envelope:

{
  "type": "result",
  "result": "...the agent's markdown response...",
  "usage": {
    "input_tokens": 312,
    "output_tokens": 847
  },
  "model": "claude-opus-4-5"
}

Full `adapter_config` Reference

{
  "model":       "claude-opus-4-5",   // required
  "max_tokens":  4096,               // default: 4096
  "temperature": 0.3,               // default: 0.7
  "timeout_ms":  60000,             // default: 60 000ms
  "api_key_env": "ANTHROPIC_API_KEY" // env var name; default: ANTHROPIC_API_KEY
}

Synchronous Execution

The claude-code adapter is synchronous — it waits for the subprocess to finish before returning. This means:

invoke() blocks until Claude responds
Returns status: 'completed' (or 'failed') immediately
status() and cancel() are no-ops (run already done)
The heartbeat tick is serialized per agent in this adapter

For most use cases this is fine. If you need parallel Claude invocations, run multiple agents with the same adapter type — each gets its own subprocess.

Error Scenarios

Error	Cause	Fix
`ENOENT: claude not found`	CLI not installed	`npm install -g @anthropic-ai/claude-code`
`401 Unauthorized`	Invalid API key	Check `ANTHROPIC_API_KEY` env var
`429 Too Many Requests`	Rate limit hit	Add retry logic or reduce heartbeat frequency
`SIGKILL (timeout)`	Response took >timeout_ms	Increase `timeout_ms` or shorten prompt
JSON parse error	CLI produced non-JSON output	Check `--output-format json` flag

Debugging a Failed Run

Find the failed heartbeat run in the Activity feed.
Click to expand — the error field shows the raw CLI output.
Or query directly:

SELECT error_detail
FROM heartbeat_runs
WHERE id = 'your-run-id';

To reproduce locally:

ANTHROPIC_API_KEY=your_key \
claude --model claude-opus-4-5 --output-format json \
  <<< "You are a researcher. Summarise PostgreSQL RLS in 2 paragraphs."

Checkpoint ✓

[ ] You understand the subprocess spawn model
[ ] You can configure model, tokens, and timeout in adapter_config
[ ] You know how to debug a failed Claude Code adapter run