claude-code-2026-04-02/docs-site/docs/architecture.md

Architecture overview

!!! warning "Recovered source" Paths refer to src/ in this repository. Line-level accuracy is best-effort from the source map reconstruction.

High-level flow

flowchart LR
  subgraph entry [Entry]
    mainTsx[main.tsx]
  end
  subgraph modes [Modes]
    repl[REPL.tsx]
    print[cli/print.ts]
    assistant[assistant KAIROS gate]
  end
  subgraph core [Core loop]
    queryLoop[query.ts queryLoop]
    qe[QueryEngine.ts]
    toolsReg[tools.ts getTools]
  end
  subgraph services [Services]
    api[services/api]
    mcp[services/mcp]
    compact[services/compact]
  end
  mainTsx --> repl
  mainTsx --> print
  mainTsx -.-> assistant
  repl --> queryLoop
  print --> qe
  queryLoop --> api
  qe --> api
  toolsReg --> mcp
  queryLoop --> compact
  qe --> compact

System design (deeper dives)

Topic	Page
Layering and dependency direction	Architectural layers
State, messages, and persistence	State and data flow
Trust, permissions, MCP policy	Security and trust model

Short orientation

• Entry — main.tsx: Commander CLI, preAction (trust, settings, telemetry gates), side-effect imports (profiler, MDM, keychain prefetch).
• Interactive host — replLauncher.tsx, screens/REPL.tsx, utils/queueProcessor.ts.
• Headless host — cli/print.ts, QueryEngine.ts, cli/structuredIO.ts.
• Tools & MCP — tools.ts, tools/*, services/mcp/, services/tools/.
• IDE / OS — bridge/, utils/deepLink/, utils/claudeInChrome/.

Key files (quick index)

Path	Role
main.tsx	CLI entry, global options, preAction
screens/REPL.tsx	Interactive session core
query.ts	Streaming query loop, tool round-trips
QueryEngine.ts	Headless query submission
cli/print.ts	Print / stream-json / SDK control transport
tools.ts / Tool.ts	Tool registry and types
services/api/client.ts, services/api/claude.ts	HTTP / streaming API
utils/permissions/	Permission modes and prompts
services/compact/	Compaction pipeline
utils/sessionStart.ts	Session / setup hooks

Further reading

• Workflows — end-to-end sequences.
• Official docs map — product docs ↔ src/.
• Reference — subsystem reference pages.
• Glossary.