Garry's Opinionated OpenClaw/Hermes Agent Brain
claude-cli — the claude-cli recipe (routes chat/toolLoop through the local claude CLI)
This page documents the claude-cli recipe as it ships. The implementation
lives at src/core/ai/recipes/claude-cli.ts and
src/core/ai/providers/claude-cli-language-model.ts.
claude-cli routes gateway.chat() and gateway.toolLoop() through the
claude CLI binary as a subprocess (claude --print ...) instead of through
the Anthropic SDK. It sits alongside the anthropic recipe as a
second Recipe entry with the same touchpoint shape; which one a given
model string resolves to is a per-call choice: anthropic:claude-sonnet-5
resolves to the native-anthropic implementation (SDK + ANTHROPIC_API_KEY),
claude-cli:claude-sonnet-5 resolves to ClaudeCliLanguageModel (subprocess,
CLI-managed auth).
Chat + query expansion — no embedding. Query expansion runs through the
same claude --print subprocess as chat, on the schemaless text path (the CLI
cannot carry a JSON schema, so the fenced JSON it answers with is parsed back),
so a brain whose utility tier points at claude-cli: keeps the multi-query
recall arm. gateway.embed() throws immediately for
claude-cli models (claude-cli has no embedding model. Use openai or google for embeddings.). Claude has no first-party embedding model regardless of
transport; pair this recipe with openai, google, or voyage for
embeddings the same way the anthropic recipe's docs recommend.
Setup
Install Claude Code 2.0.60 or newer (the
claudeCLI) and runclaudeonce to log in. Older CLIs reject the provider's flags, and the call fails withclaude CLI 2.0.60 or newer required (found <version>); upgrade Claude Code. If the binary is not onPATH, point the gateway at it explicitly:export GBRAIN_CLAUDE_CLI_BIN=/path/to/claudePoint a model tier (or any per-call model string) at
claude-cli::gbrain config set models.tier.subagent claude-cli:claude-sonnet-5Any of the models the recipe declares work the same way:
claude-cli:claude-opus-5,claude-cli:claude-haiku-4-5-20251001, etc. Short aliases (claude-cli:sonnet,claude-cli:haiku,claude-cli:opus) resolve the same way theanthropicrecipe's aliases do.
The recipe declares auth_env: { required: [] }, and neither the recipe
nor the adapter code reads or passes any API-key-shaped config value to the
subprocess — whatever the claude binary does for its own auth (see below)
is between it and its own login state, not something gbrain's config layer
participates in. There is also no provider_base_urls entry for this
recipe — it has no base URL, only a subprocess binary path
(GBRAIN_CLAUDE_CLI_BIN).
What actually happens on a call
Each doGenerate call spawns claude --print --output-format json --verbose --model <id> --disable-slash-commands --tools '' --strict-mcp-config --settings '{"disableAllHooks":true}' as a
subprocess, with cwd set to a per-process directory under the OS tmpdir
(join(tmpdir(), 'gbrain-claude-cli-cwd-' + process.pid), created via
mkdirSync(..., { recursive: true }) if missing — code doesn't otherwise
touch or inspect its contents), and pipes the rendered prompt to it on
stdin:
--verbosemakes stdout the session's event array rather than the bare result envelope. When a response hits its output cap, Claude Code continues it on its own with a second request, and the envelope'sresultholds only the text after that point. The adapter rebuilds the full answer from the call's assistant events. When it cannot prove the rebuilt text is the whole answer, the call returns no text and no tool calls, finisheslength(so callers retry or escalate, as for any capped answer) and reportsproviderMetadata['claude-cli'].code = 'continuation_unproven'with its reason. The gateway keeps that result as it is: thechat_fallback_chaindoes not resend it (only refusals and thrown errors move to the next model), andtoolLoopstopslengthwithout dispatching a tool.--tools ''disables every built-in tool (Bash/Read/WebSearch/…) — the subprocess must behave like a raw LLM, not a full agent.--strict-mcp-configskips loading the user's MCP servers. Without it, every call would boot the user's configured MCP servers — including gbrain's own MCP, which would recurse and contend for the PGLite single-writer lock.--settings '{"disableAllHooks":true}'stops the child from running your Claude Code hooks (user and project settings). Without it, gbrain's own Stop hook would bank every claude-cli call's prompt as one of your conversations, and extracting facts from it would spawn another call. Your login is unaffected: credentials are not settings. Hooks from a managed policy file (/etc/claude-code/managed-settings.jsonon Linux) are a different case. Claude Code 2.1.287 still runs them, because policy wins over--settings; 2.0.60 suppressed them too (probed with a managed SessionStart and Stop hook on Linux). A managed policy that installs gbrain's own hooks therefore still fires inside claude-cli calls; gbrain's Stop hook, the serve-side harvest and the sweep all skip those self-captures, so nothing is extracted from them.- A call with an output cap carries it as
CLAUDE_CODE_MAX_OUTPUT_TOKENSin both the--settingsenv and the child env. Claude Code thinks by default on Claude 5 models, and the API needs a thinking budget of at least 1024 tokens below that cap, so a call capped at 1024 tokens or fewer (themodels doctorprobe, query-intent and classification calls) also setsMAX_THINKING_TOKENS=0in both places and reportsproviderMetadata['claude-cli'].thinking = 'disabled_below_floor'. A larger cap leaves thinking to the CLI. - The subprocess env is a copy of gbrain's own process env with the
cloud-auth routing variables scrubbed before spawn: the three direct-API
keys (
ANTHROPIC_API_KEY,ANTHROPIC_AUTH_TOKEN,ANTHROPIC_BASE_URL) plus everyCLAUDE_CODE_USE_*backend-switch flag (a prefix wipe, not a denylist — Bedrock, Vertex AI, and the other cloud backends are each gated by one of these, take priority over subscription OAuth when set, and route billing through a cloud account; clearing the switch is sufficient because the provider-specific credentials are inert without it). Everything else in gbrain's environment is inherited as-is. Subscription-only is the recipe's contract: children always authenticate with the CLI's own login state. If you intentionally route a workload through a cloud backend, use theanthropicrecipe with cloud credentials instead — the scrub means claude-cli children will not inherit that routing. Whatever auth/billing configuration the installedclaudebinary carries in its own config files (not env) remains between it and its login state. - Beyond that env-scrub, auth resolution is entirely up to the installed
claudebinary — the recipe does not manage or forward credentials itself. Whateverclaudeis already logged in / authenticated with on this machine is what it authenticates with here too (see theclaudeCLI's own docs for how it stores and resolves that).
--bare (which would skip loading the user-level ~/.claude/CLAUDE.md
entirely) is not among the flags passed, because it also forces
ANTHROPIC_API_KEY auth (per the recipe's source comment). On Claude Code
2.1.314 or newer the child gets --setting-sources "" instead, so your
user-level ~/.claude/CLAUDE.md, memory and settings.json stay out of
every call and the login is kept (gbrain reads claude --version once per
binary per process). An older CLI still loads them on every call.
Trade-off: --setting-sources "" loads no settings source at all, so the
env block, apiKeyHelper and permission rules in your settings.json don't
reach the child either. The subscription (OAuth) login is kept, but a claude
login or proxy that depends on settings.json doesn't apply to gbrain's
claude-cli calls on these versions. To load them again, set
GBRAIN_CLAUDE_CLI_USER_SETTINGS=1 in the environment gbrain runs in (your
shell or ~/.gbrain/.env; a project .env can't set it): the child then gets
no --setting-sources flag and gbrain skips the version probe.
The adapter does not use claude's own agentic tool-calling — it injects a
fenced instruction block into the system prompt teaching the model a
<use_tools>[{id,name,input}, ...]</use_tools> JSON emission format
(buildToolUseInstructions), then parses that block back out of the plain
text response into ai-sdk tool-call parts (extractToolCalls). Tool-call
ids are minted locally (toolu_claude_cli_<counter>_<random>), never
trusted from the model: each --print turn is a fresh subprocess with no
memory of prior ids, so model-chosen ids repeat across turns and would
collide with the per-job tool-id uniqueness constraint; nothing ever echoes
the original id back to the subprocess, so the substitution is transparent
to the tool-result pairing. This
protocol-over-text approach is what lets supports_subagent_loop: true
work through the --print, no-built-in-tools subprocess shape described
above.
Constraints
| Area | Behavior |
|---|---|
| Embedding | Not supported — gateway.embed() throws for claude-cli models. Pair with another provider for embeddings. |
| Streaming | Not implemented. doStream() throws. gateway.toolLoop() (the main caller) is non-streaming already, so this is not a practical limitation for subagent dispatch, but any caller that expects a streaming chat surface cannot use claude-cli. |
| Tool use | JSON emission via a system-prompt-injected protocol, not the CLI's native tool-call mechanism. Parallel tool calls in one turn round-trip correctly. |
| Multimodal | Not supported over the subprocess path. File/image message parts are rendered as a [file <mediaType>] text stub, not sent as actual content. |
| Prompt caching | The recipe declares supports_prompt_cache: true: Claude Code caches prompt prefixes itself on every --print run (Anthropic's Claude Code docs put -p runs in the main-conversation TTL bucket — one hour on a subscription, five minutes on an API key). gbrain cannot place cache_control breakpoints on this path — the adapter renders messages to stdin text and ignores providerOptions — so caching is automatic rather than gateway-driven, and doctor's subagent_capability does not grade a claude-cli subagent tier degraded:no_caching. cache_read_input_tokens is surfaced as usage.cachedInputTokens (next row). |
| Usage / token counts | Reported usage.input_tokens / usage.output_tokens are read straight from the CLI's --output-format json envelope (result.usage?.input_tokens / output_tokens); gbrain does not independently count tokens for this path. The envelope's cache_read_input_tokens is surfaced as usage.cachedInputTokens, so cache reads are counted in gbrain's usage accounting; cache_creation_input_tokens is not surfaced (the AI SDK's usage shape has no corresponding field). |
| Cost figures | The recipe declares cost_per_1m_input_usd: 3.0 / cost_per_1m_output_usd: 15.0 — the same Sonnet-class figures the anthropic recipe declares (price_last_verified: 2026-06-17) — purely so gbrain's budget ledger has a number to attribute per call. Neither the recipe nor the adapter code checks what you're actually billed; treat these as the ledger's nominal per-call number, not a verified charge. The --max-usd / --max-cost budget gate does not read them either: it prices claude-cli:<model> at the nominal Anthropic rate for that model, and a short alias (claude-cli:haiku) prices identically to the dated id it resolves to; pricing.overrides forces $0 or a real rate for any claude-cli:* string, and on a subscription one line prices every claude-cli model: gbrain pricing set 'claude-cli:*' --rate 0 (an exact model entry still wins; at $0 no cap limits claude-cli calls). |
| User-level CLAUDE.md | Kept out on Claude Code 2.1.314 or newer (--setting-sources ""); an older CLI loads ~/.claude/CLAUDE.md on every call (see above). Otherwise only the working directory changes (see "What actually happens on a call" for exactly what that directory is and isn't). |
Doctor probe timeout: per-recipe, 30s for claude-cli
gbrain models doctor's chat reachability probe (probeModel in
src/commands/models.ts) resolves its timeout per model: the recipe
touchpoint's declared default_timeout_ms when present, else a flat 5000ms
default (the right number for a plain HTTP round-trip). The claude-cli
recipe declares default_timeout_ms: 30_000 because each call spawns a
claude -p subprocess (CLI cold start + user-level CLAUDE.md load) that
routinely takes 5-6 seconds even when the CLI and subscription are perfectly
healthy; a flat 5s abort would false-fail the probe on every run with
status: unknown (claude-cli adapter aborted) while chat() succeeds
at normal call sites.
30 seconds gives the subprocess room to start without masking a truly
dead or unauthenticated CLI for long. A probe that still outruns 30s kills
the subprocess (child.kill('SIGTERM')) and reports status: unknown —
the adapter's abort message doesn't match classifyError's network
patterns, so it lands in the catch-all. A persistent unknown is worth
investigating directly (run the same model via gbrain models doctor --json or call claude by hand) rather than assuming cold-start.
Falling back to an API model at the subscription limit
When the Claude subscription's usage window is used up, the CLI reports
claude-cli API error 429: You've hit your session limit · resets <time>.
chat_fallback_chain retries the same call on the next model in the chain
instead of failing it:
gbrain config set chat_fallback_chain "anthropic:claude-sonnet-4-6"
gbrain doctor --only chat_fallback_chain --json
Say to your agent: "When my Claude subscription runs out, fall back to an API model instead of failing."
The chat fallback guide covers the chain for
every provider: prerequisites, the env / config.json / database planes and
their precedence, refusal fallback and chat_fallback_on_refusal, the doctor
check, removal and hosted brains. Two points are specific to claude-cli:
- The subscription limit arrives as a provider error (
apiErrorStatus429), so the chain treats it like any outage; when every entry fails, the claude-cli error is the one reported. - Every call still tries the claude-cli model first, so during the limit window each call pays one failed CLI spawn before the fallback runs.
Troubleshooting
| Symptom | Where it comes from | Try | Who acts | Consent | Verify |
|---|---|---|---|---|---|
claude-cli spawn failed: ... / stdin write failure |
spawn()'s error event or a failed stdin.write — commonly means the claude binary was not found on PATH |
Install Claude Code, or set GBRAIN_CLAUDE_CLI_BIN to the binary's path |
user | persistent_install (installs Claude Code) |
gbrain models doctor --json (one tiny call per model) |
claude-cli API error <status>: <message> |
The CLI reported an API failure in its result envelope (is_error: true with api_error_status, e.g. 429 on a spend/rate limit) — surfaced whether the subprocess exited non-zero or zero. The error is a ClaudeCliProcessError carrying apiErrorStatus + exitCode for programmatic handling |
Read the message — it's the CLI's own human-readable explanation (e.g. a spend-limit notice with the fix URL) | user (a spend or rate limit is theirs to lift) | none | gbrain models doctor --json (one tiny call per model) |
claude-cli reported error: <message> |
Same envelope-reported failure (is_error: true) but without an api_error_status field |
As above — the message is the CLI's own explanation | user | none | gbrain models doctor --json (one tiny call per model) |
claude CLI 2.0.60 or newer required (found <version>); upgrade Claude Code |
The installed CLI's argument parser rejected one of the provider's flags (error: unknown option … after the --- raw --- marker); 2.0.59 and older reject --disable-slash-commands |
Upgrade Claude Code (claude update, or reinstall), then rerun |
user | persistent_install |
claude --version |
claude-cli exited <code> + --- raw --- blob |
Non-zero exit from the claude subprocess where stdout carried no parseable result envelope; the CLI's stderr/stdout follows the --- raw --- marker (kept behind the marker so error classifiers never phrase-match model-derived text) |
Run claude interactively with the same model to see the underlying CLI error directly (e.g. not logged in, model unavailable) |
user (log in, pick an available model) | credentials when logging in |
gbrain models doctor --json (one tiny call per model) |
claude-cli output not JSON: ... |
JSON.parse(stdout) threw (stdout wasn't valid JSON at all) |
Confirm the installed claude CLI version still supports --print --output-format json; this adapter's JSON handling was verified against CLI 2.1.145 |
agent | none | claude --version |
claude-cli JSON event array had no "result" event |
stdout parsed as the --verbose event array but none of the events had type: "result" (the run ended before reporting) |
Run claude --print --output-format json --verbose by hand with the same model to see where it stops |
agent | none | gbrain models doctor --json (one tiny call per model) |
[claude-cli] continuation_unproven (<reason>) on stderr (once per reason per process); the call finishes length with no text |
The answer hit its output cap and Claude Code continued it, and stdout could not prove the full text: the bare envelope without the event array (events_missing), an event array with no assistant message (no_assistant_events), or assistant segments that do not provably make up this answer (segments_unmatched) |
Callers treat it as a capped answer and retry or escalate. events_missing and no_assistant_events: upgrade the claude CLI so --output-format json --verbose prints the session's assistant events. segments_unmatched: raise the caller's output cap (the setting its truncation warning names) |
agent | none | rerun the call; a raised cap or an upgraded CLI finishes stop |
gbrain models doctor reports chat as status: unknown for a claude-cli: model |
The probe allows 30s for the subprocess (see "Doctor probe timeout" above); a persistent unknown means the call genuinely failed or outran even that window — classifyError falls through to unknown for the adapter's abort message |
Investigate directly: run the same model via gbrain models doctor --json or call claude by hand (e.g. not logged in, model unavailable) |
agent | none | gbrain models doctor --json (one tiny call per model) |
| A call bills through the Anthropic API or a cloud backend instead of the local session | The adapter deletes ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL and every CLAUDE_CODE_USE_* backend-switch flag from the subprocess env — this covers gbrain's own env leaking into the call. It does not inspect billing switches the installed claude CLI carries in its own config files |
If billing looks wrong, check the claude CLI's own auth/billing configuration on this machine, not just gbrain's env. For intentional cloud routing, use the anthropic recipe instead |
user | none | the claude CLI's own auth status on this machine |