Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
Architecture — engineering rationale
Why the code is shaped the way it is: what was measured, what it cost, and what breaks if you change it. None of this is recoverable by reading the source, which is the test for whether something belongs here.
Extracted from CLAUDE.md in v7.64.0. That file is prepended to every session, so it had grown
to 1,531 lines — 156 KB of prompt on every turn, most of it needed only when working in one
specific area. It now holds only the operational core — commands, release steps, and the
invariants that fail silently — plus a list naming which document covers what.
Tracked deliberately, like ai-docs/reports/. These started life in CLAUDE.md precisely
because ai-docs/sessions/ is gitignored and does not survive git worktree remove — the way
three earlier write-ups this material cites were lost.
Documents
| Document | What it covers | Read it before you… |
|---|---|---|
routing.md |
The provider@model syntax, the full provider-prefix table, local models, which names reach route() (proxyRouteDecision and the parse gate), where a bare name's chain comes from now that there is NO built-in rules table, the fallback hop and its three empty states, wire ids from the catalog's connections, route bindings vs the lookup-only names, the DERIVED picker provider list, and why subscription pricing is decided by billing rather than by modelDiscovery |
change proxyRouteDecision, the parser's fallback, explainBareName or explainRoute, route-candidates.ts, catalog-route-bindings.ts, a nativeModelPatterns claim, defaultProvider, the picker, or SUBSCRIPTION_PROVIDERS |
providers/devin.md |
The only binary wire in the pipeline — Connect envelopes carrying protobuf, live uid resolution, errors that ride an HTTP 200, and the three wire facts that cost real money to get wrong | touch providers/devin/, the codec, or dv@ model resolution |
providers/grok-subscription.md |
gk@ on a SuperGrok / X Premium+ plan: RFC 8628 device flow, exact-scope matching, 6-hour token refresh with write-back, three mandatory client headers |
touch gk@, claudish login grok, or its OAuth refresh |
providers/antigravity.md |
Gemini on an Antigravity subscription: the shared agy keychain token, runtime client-secret extraction, live discovery of the account's dynamic models catalog |
touch ag@, auth/antigravity-*, or the keychain token |
providers/qwen-alibaba.md |
One service, two consoles, three isolated key+host products and account-discovery caveats | touch qcode@/qtoken@/qpay@, or assume anything about Alibaba's credentials |
providers/meta-muse-code.md |
muse@ on a Muse Code subscription: the Responses wire and the ignored response.subscription_usage event, the Muse CLI's Keychain item and the borrowed 0600 copy, the per-process prompt role, the never-killed security read and its per-machine lock, the mint as entitlement evidence with per-process, 401 and 30-minute rotation, the unused /v1/messages and /v1/chat/completions, the contributor guard and its removal trigger, backend M1 to M6 |
touch providers/meta-muse/, transport/meta-muse-code.ts, muse-code-credential.ts, prompt-role.ts, content-use.ts, claudish login muse, or the metered meta@ |
custom-endpoints.md |
User-defined customEndpoints: schema, ${VAR} expansion, and authScheme: "none" for endpoints that take NO credential |
change customEndpoints, config-schema.ts, or authScheme handling |
predefined-endpoints.md |
The 25-vendor bundled catalog: credential-gated activation, the single registration seam, evidence tiers (all probe, none live), and the no-model-data rule |
add a vendor to providers/predefined-catalog.ts, or change endpoint registration |
credential-files.md |
A long-lived process follows its credential FILE: the stat-and-reload on change (no timer), the four disk states and why "unreadable" never signs a subscription user out, compare-and-set on the refresh-token lineage so a refresh cannot undo a login, lazy first load (Kimi's import-time read), the residual window and its removal trigger, what is logged | touch credential-file.ts, oauth-manager.ts, grok-oauth.ts, kimi-oauth.ts, devin-credentials.ts, the ~/.grok/auth.json write-back, or add a file-backed OAuth login |
onepassword.md |
SDK-only secret resolution, the FOUR causes of an identical denial error, the cross-process handshake lock, parent-side route pinning, and the config TUI tab | touch providers/onepassword*.ts, credential pre-hydration, or the 1Password TUI tab |
keychain.md |
The macOS Keychain backend: the 17ms-vs-28ms measurement that split presence from values, the two security behaviours that are traps (hex reads, a "secure" write that stores nothing and exits 0), and why no new CredentialSource member |
touch providers/keychain.ts, keychain-source.ts, or the Providers tab's key write/delete |
wire.md |
Every request from the connection's catalog wire and the route registry: the four-step pipeline, Jack's decisions where they diverge from the backend spec (clamp, borrow-and-drop, try in turn), the first-run refusal that stuck for a session, + doubling as the chain separator, name gates one layer down, custom endpoints' declared wire, the advisor and discovery on registry hosts |
touch connection-*.ts, wire-*.ts, declared-wire.ts, ComposedHandler step 5w, an adapter's limit or reasoning fields, the advisor's request, or +/# model-spec markers |
adapters.md |
Layers 1–3 (FormatConverter / ModelTranslator / ProviderTransport), stream-parser selection, errors that ride an HTTP 200, and the upstream_status remap with its downstream readers |
add a provider, model translator, or stream parser; or change error classification and retry |
code-mode.md |
--code-mode for openai-codex: one freeform exec tool running JavaScript in a QuickJS sandbox, nested calls relayed as tool_use blocks; the decision and why its gates run in that order, the lite and classic shapes and the lite → classic fallback, the request-scoped binding and the account/session keys, step 5r resume and its tombstones, the input builder (turn records, classic rounds transliterated), the store byte ceilings, and the sandbox measurements (handle ownership, wasm growing to 2 GiB under a 32 MiB heap limit, hence the 256 MiB ceiling per module, retire-and-replay past it) |
touch code-mode/, step 5d or 5r, the Responses leg parser's exec handling, the turn driver's code-mode hooks, or the sandbox limits |
network-recovery.md |
The two-tier connection hold: why the deadline is DERIVED from API_TIMEOUT_MS (measured 359.607 s, a default and not a watchdog), why the tier-2 status is 503 and never 429, why the banner is magmux's overlay and never a pane of ours (closing a pane wedged Claude Code), why its lease is renewed on its own tick and not by ladder events, the five sites where a network failure wore an auth status code, and why a pane child gets no watchdog |
touch the retry ladder, recovery/, the tier-2 status, the recovery banner, or any x-claudish-recovery reader |
hooks.md |
The hook system, which replaced the behavior layer and the MiddlewareManager: closed actions and severity, the process topology and the owner-created inbox, request stages A and B, the response seam's three stages and opt-in buffering, the raw tier's transactional containment, hook output kept off the MCP protocol stream (dup2), the settle hold (SETTLING, record then conclude, turn chains), the interactive driver; plus the harness-convention SUPERVISOR rationale, the 115-call plan-mode measurement and opt-in telemetry |
write or change a hook or built-in hook, touch hooks/, the response seam, a stream parser's raw tap, the settle hold, or harness-conformance handling |
advisor.md |
--advisor for any main model: why it is independent of --monitor yet keeps four of its launch bits, the decorator around the ROUTED handler, id capture by tool name (the toolu_ prefix that made it a no-op on every foreign provider), the tee and retained session-keyed state, the ten stub paths and advice origin, Claude Code's advisor gates, metered panel billing, and the inherited-placeholder 401 |
touch --advisor, advisor-decorator.ts, native-handler-advisor.ts, advisor-startup.ts, monitor-gated launch code, or native auth in claude-runner.ts |
headless-vs-interactive.md |
Why -p is NOT interactive-without-a-TTY: an UNKNOWN --agent is SILENTLY unvalidated under --input-format stream-json (measured, exit 0, no stream frame, result: success), upstream closed it as not planned, why magmux is in the dependency tree, the one -p the MCP server starts (run_prompt on a Claude model) and why it is safe, and why a driver cannot rely on magmux's pane states |
drive Claude Code headlessly, add a child-spawn flag, or assume a headless run behaves like an interactive one |
pane-session.md |
MCP team slots, CLI team and create_session as interactive Claude Code in headless magmux panes: the transcript as turn oracle, boot from screen content and closed dialog lists ("never accept"), the four settle paths with the measured secondaryQuietMs (32 s), prompt delivery by file with read coverage and exact require_pattern semantics, the environment snapshot and shell shim, one level of nesting (inMcpSession/isPaneChild, the nested refusal), the pane watcher and the identity-checked reap, the socket traps, seq ownership, the D9/D10 bounds, the phase table, and the frozen mod contract v1 |
edit pane/, team or MCP session spawn, the settle rule, prompt delivery, the reap or sweep, or any field the mod contract carries |
picker.md |
The OpenTUI model picker: why it is an inline dialog and not a dashboard (the density gate that manufactured the rejected build), the provider list as the default screen with nothing prefetched (3915 → 1436 ms), the discovery outcome that stopped [] meaning five things, the local served-by index (22 network queries measured at 10 018 ms), the no-terminal gate's complement law, and the capture and compile traps |
change picker/, selectModel, discovery outcomes or fetchers, should-open-picker.ts, or a TUI test that asserts on a frame |
context-window.md |
Why setting one env lever accomplishes nothing, why the status line reports the ENFORCED window, and local-model token accounting | change context-window resolution, the status line, or token accounting |
theming.md |
One detected theme for every surface, and the module-load palette-snapshot bug class it keeps producing (found six times) | add a colored CLI line or TUI surface |
mcp-sessions.md |
The 15-tool MCP surface (groups low-level / agentic / session / debug, CLAUDISH_MCP_TOOLS; capture_session and resize_session in the session group) and the 4-tool nested-mode surface, sessions on panes: the flag check, the owner's verdict, send_input queueing, the session records (spawn.json, waits.jsonl, meta.json, events.jsonl, screen.txt, and the hook inbox) and who reads them, get_diagnostics; run_prompt's two paths (the Claude Code print call on the user's login, the proxy with no max_tokens); why the channel push was removed; and the notifications/progress keepalive |
add or rename an MCP tool or group, change run_prompt or nested mode, or change sessions or their records |
team-capture.md |
Why exit 0 proves nothing under claude -p (the measurement behind require_pattern), and why a slot's answer is every assistant message of its turn, read from the transcript, starting after the task file was read |
change how team classifies output or builds response-<slot>.md |
team-lifecycle.md |
Why nothing kills a slot on a timer, the measurement that removed the deadline, why run returns once every prompt is accepted (≤ 120 s), the run registry by run_id, the blocked rule, the team record ended exactly once, and one driver with two owners |
add a deadline, change when team returns, or touch per-slot liveness, cancel or the run record |
debugging.md |
Debug logging, CLAUDISH_UPSTREAM_ERROR_LOG, raw SSE capture, and the failed-translation workflow |
diagnose a model producing wrong, empty, or garbled output |
testing.md |
The SSE-replay format-translation harness, the shared resources a test must never reach, hermetic pane tests (a real magmux, the fake child, the allowlisted env, the no-orphan assertion, "not checked" skips, time seams) and the opt-in live pane tests | add a format-translation regression test, or write or run a test that spawns a pane |
Neighbours
ai-docs/reports/— measurement evidence these documents cite (probe results, live runs, protocol specs).ai-docs/benches/— reusable evals.ai-docs/sessions/— GITIGNORED scratch space. Work there; put conclusions here or inreports/.docs/— the published, user-facing site.docs/three-layer-architecture.mdis a fuller treatment of Layers 1–3 under different names (APIFormat/ModelDialect) and carries its own name-mapping section;adapters.mdis the shorter operational view.