docs: add internal architecture deep-dive with diagrams

[omarjmh]

Summary

Adds docs/internals/ — a 14-part, code-grounded explanation of how the Claude Code CLI works internally, with 42 Mermaid architecture diagrams.

Covers, one doc per subsystem (each with file:line anchors + a key-symbols table):

• Startup & entrypoints, the agentic query loop, context/prompt assembly + compaction
• Tool system, slash commands, permissions
• Services (API/auth/analytics/cost), MCP, multi-agent/coordinator/tasks
• React+Ink UI/state, bridge/remote/server surfaces, plugins/skills/memory, build system + feature flags

Also adds a discoverability pointer from docs/architecture.md.

Notes

• Documentation only — no changes to src/.
• Diagrams are Mermaid (render on GitHub). Start at docs/internals/README.md.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive internal architecture documentation guide with Mermaid diagrams and detailed walkthroughs covering system startup, query loop execution, context and prompt building, tool mechanisms, slash commands, permissions, API authentication, MCP integration, multi-agent coordination, UI rendering, remote sessions, plugin/skill extensibility, and build configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7db91801-70f8-4e30-810f-1a35073e7301

📥 Commits

Reviewing files that changed from the base of the PR and between 6a25909 and e3233b6.

📒 Files selected for processing (15)

• docs/architecture.md
• docs/internals/01-startup.md
• docs/internals/02-query-loop.md
• docs/internals/03-context-and-prompts.md
• docs/internals/04-tools.md
• docs/internals/05-commands.md
• docs/internals/06-permissions.md
• docs/internals/07-services-api-auth.md
• docs/internals/08-mcp.md
• docs/internals/09-agents-coordinator-tasks.md
• docs/internals/10-ui-state-rendering.md
• docs/internals/11-bridge-remote-server.md
• docs/internals/12-plugins-skills-memory.md
• docs/internals/13-build-config-flags.md
• docs/internals/README.md

---

📝 Walkthrough

Walkthrough

Adds docs/internals/ containing 13 numbered subsystem documentation pages and a README index covering the Claude Code internal architecture end-to-end (startup, query loop, context/prompts, tools, commands, permissions, API/auth, MCP, agents, UI, bridge/remote/server, plugins/skills/memory, and build/config flags), plus a callout added to the existing docs/architecture.md.

Changes

Internal Architecture Documentation

Layer / File(s)	Summary
Overview index and architecture.md callout docs/architecture.md, docs/internals/README.md	docs/internals/README.md is created with a full deep-dive index: agent loop explanation, system-layer Mermaid diagram, one-turn end-to-end flow, directory-to-subsystem map, and glossary. docs/architecture.md gains a callout pointing to the new guide.
Startup flow and query loop docs/internals/01-startup.md, docs/internals/02-query-loop.md	01-startup.md documents entrypoints, boot sequence ordering, CLI fast-path vs Commander parsing, STATE singleton, parallel prefetch, and REPL handoff. 02-query-loop.md explains query()/queryLoop() structure, per-iteration steps (context reduction, model call, streaming, tool execution), recovery paths for multiple error classes, and the QueryEngine wrapper.
Context/prompts construction and tool catalog docs/internals/03-context-and-prompts.md, docs/internals/04-tools.md	03-context-and-prompts.md documents three LLM request inputs, system-prompt priority selection, prompt caching boundary/cache-control rules, the five-layer compaction pipeline (including autocompact sub-query and 413 recovery), and mid-turn attachment injection. 04-tools.md covers the Tool contract, ToolUseContext, catalog build pipeline, Zod-to-JSON-Schema serialization, concurrency partitioning, deferred tools, tool inventory table, and directory anatomy.
Slash commands and permission system docs/internals/05-commands.md, docs/internals/06-permissions.md	05-commands.md defines the discriminated Command union, registry assembly, dispatch/routing flow, prompt-to-LLM propagation, forked execution via executeForkedSlashCommand, and a built-in command inventory. 06-permissions.md documents the "first match wins" decision pipeline, PermissionMode values, rule model and precedence table, mode === 'auto' classifier, and PreToolUse hook integration.
API/auth/services and MCP integration docs/internals/07-services-api-auth.md, docs/internals/08-mcp.md	07-services-api-auth.md covers the end-to-end API call path (streaming + non-streaming fallback), retry/backoff/FallbackTriggeredError, OAuth/PKCE auth resolution and keychain storage, GrowthBook analytics/flags, cost tracking with cache pricing tiers, and a "Key symbols" table. 08-mcp.md documents MCP client config/connection/discovery/naming, the claude mcp serve server entrypoint, and the separate mcp-server/ npm package.
Agents/coordinator/tasks and UI rendering docs/internals/09-agents-coordinator-tasks.md, docs/internals/10-ui-state-rendering.md	09-agents-coordinator-tasks.md describes nested query() sub-agents, sync vs async/background isolation via AsyncLocalStorage, fork cache sharing, coordinator mode, task lifecycle/notification queue, inter-agent team messaging, and a concurrency-model comparison table. 10-ui-state-rendering.md covers React/Ink rendering, REPL event-stream handling, AppState dual-state model, message rendering pipeline, input handling stack, and headless print mode.
Bridge/remote/server, plugins/skills/memory, and build/config docs/internals/11-bridge-remote-server.md, docs/internals/12-plugins-skills-memory.md, docs/internals/13-build-config-flags.md	11-bridge-remote-server.md explains Bridge (CCR) protocol/JWT/crash-recovery, RemoteSessionManager WebSocket model, and Server mode PTY lifecycle. 12-plugins-skills-memory.md documents skills/plugins/persistent memory/output-styles extensibility. 13-build-config-flags.md covers the esbuild/Bun build pipeline, build-time feature flags with dead-code elimination, Zod config schema, and startup migrations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 Hippity-hop through the docs I go,
Thirteen pages of internals to know!
The query loop spins, the tools take their turn,
Permissions say "ask" while the bridges all burn.
With Mermaid diagrams and symbols galore,
This rabbit now knows what the code has in store! 🗺️

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the main change: adding comprehensive internal architecture documentation with diagrams to the docs/internals directory.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}