iframe-proxy

omarjmh · 2026-06-15T15:33:47Z

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.

Add docs/internals/ — a 14-part, code-grounded explanation of how the Claude Code CLI works internally, with 42 Mermaid architecture diagrams. Covers: startup/entrypoints, the agentic query loop, context & prompt assembly + compaction, the 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, and the build system + feature flags. Each subsystem doc includes file:line anchors and a key-symbols table. Also adds a discoverability pointer from docs/architecture.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-06-15T16:02:44Z

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)

_{✏️ 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

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

Sunbelt Computer Software

PL/B Language Development and Support

Navigation Menu

Repository navigation

docs: add internal architecture deep-dive with diagrams - #15

docs: add internal architecture deep-dive with diagrams#15
omarjmh wants to merge 1 commit into
codeaashu:mainfrom
omarjmh:docs/internals-architecture-deepdive

omarjmh commented Jun 15, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 15, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Sunbelt Computer Software

PL/B Language Development and Support

Conversation

omarjmh commented Jun 15, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Notes

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

omarjmh commented Jun 15, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 15, 2026 •

edited

Loading