Claude Code Architecture Study
Introduction: This project is a learning and research repository focused on CLI Agent architecture. All materials are compiled entirely from publicly available online references and discussions, with a particular focus on public information regarding the highly popular CLI Agent claude-code. Our intention is to help developers better understand and utilize Agent technologies. We will continue to share more insights and practical discussions on Agent architecture in the future. Thank you for your support!
Disclaimer: All content in this repository is provided strictly for technical research, study, and educational exchange among enthusiasts. Commercial use is strictly prohibited. No individual, organization, or entity may use this content for commercial purposes, profit-making activities, illegal activities, or any other unauthorized scenarios. If any content infringes upon your legal rights, intellectual property, or other interests, please contact us and we will verify and remove it immediately.
Language: English | 中文 | 한국어 | 日本語
Table of Contents
Deep Analysis Reports (docs/)
Deep analysis reports compiled from publicly available online references and community discussions on Claude Code v2.1.88. Quadrilingual (EN/JA/KO/ZH).
docs/
├── en/ # English
│ ├── [01-telemetry-and-privacy.md] # Telemetry & Privacy — what's collected, why you can't opt out
│ ├── [02-hidden-features-and-codenames.md] # Codenames (Capybara/Tengu/Numbat), feature flags, internal vs external
│ ├── [03-undercover-mode.md] # Undercover Mode — hiding AI authorship in open-source repos
│ ├── [04-remote-control-and-killswitches.md]# Remote Control — managed settings, killswitches, model overrides
│ └── [05-future-roadmap.md] # Future Roadmap — Numbat, KAIROS, voice mode, unreleased tools
│
├── ja/ # 日本語
│ ├── [01-テレメトリとプライバシー.md] # テレメトリとプライバシー — 収集項目、無効化不可の理由
│ ├── [02-隠し機能とコードネーム.md] # 隠し機能 — モデルコードネーム、feature flag、内部/外部ユーザーの違い
│ ├── [03-アンダーカバーモード.md] # アンダーカバーモード — オープンソースでのAI著作隠匿
│ ├── [04-リモート制御とキルスイッチ.md] # リモート制御 — 管理設定、キルスイッチ、モデルオーバーライド
│ └── [05-今後のロードマップ.md] # 今後のロードマップ — Numbat、KAIROS、音声モード、未公開ツール
│
├── ko/ # 한국어
│ ├── [01-텔레메트리와-프라이버시.md] # 텔레메트리 및 프라이버시 — 수집 항목, 비활성화 불가 이유
│ ├── [02-숨겨진-기능과-코드네임.md] # 숨겨진 기능 — 모델 코드네임, feature flag, 내부/외부 사용자 차이
│ ├── [03-언더커버-모드.md] # 언더커버 모드 — 오픈소스에서 AI 저작 은폐
│ ├── [04-원격-제어와-킬스위치.md] # 원격 제어 — 관리 설정, 킬스위치, 모델 오버라이드
│ └── [05-향후-로드맵.md] # 향후 로드맵 — Numbat, KAIROS, 음성 모드, 미공개 도구
│
└── zh/ # 中文
├── [01-遥测与隐私分析.md] # 遥测与隐私 — 收集了什么，为什么无法退出
├── [02-隐藏功能与模型代号.md] # 隐藏功能 — 模型代号，feature flag，内外用户差异
├── [03-卧底模式分析.md] # 卧底模式 — 在开源项目中隐藏 AI 身份
├── [04-远程控制与紧急开关.md] # 远程控制 — 托管设置，紧急开关，模型覆盖
└── [05-未来路线图.md] # 未来路线图 — Numbat，KAIROS，语音模式，未上线工具
Click any filename above to jump to the full report.
| # |
Topic |
Key Findings |
| 01 |
Telemetry & Privacy |
Two analytics sinks (1P, Datadog). Environment fingerprint, process metrics, repo hash on every event. No UI-exposed opt-out for 1st-party logging. OTEL_LOG_TOOL_DETAILS=1 enables full tool input capture. |
| 02 |
Hidden Features & Codenames |
Animal codenames (Capybara v8, Tengu, Fennec→Opus 4.6, Numbat next). Feature flags use random word pairs (tengu_frond_boric) to obscure purpose. Internal users get better prompts, verification agents, and effort anchors. Hidden commands: /btw, /stickers. |
| 03 |
Undercover Mode |
Official employees auto-enter undercover mode in public repos. Model instructed: "Do not blow your cover" — strip all AI attribution, write commits "as a human developer would." No force-OFF exists. Raises transparency questions for open-source communities. |
| 04 |
Remote Control |
Hourly polling of /api/claude_code/settings. Dangerous changes show blocking dialog — reject = app exits. 6+ killswitches (bypass permissions, fast mode, voice mode, analytics sink). GrowthBook flags can change any user's behavior without consent. |
| 05 |
Future Roadmap |
Numbat codename confirmed. Opus 4.7 / Sonnet 4.8 in development. KAIROS = fully autonomous agent mode with <tick> heartbeats, push notifications, PR subscriptions. Voice mode (push-to-talk) ready but gated. 17 unreleased tools found. |
Copyright & Disclaimer
This repository is provided strictly for technical research and educational purposes.
Commercial use is strictly prohibited.
If you are the copyright owner and believe this repository content infringes your rights,
please contact the repository owner for immediate removal.
Stats
| Item |
Count |
| Files (.ts/.tsx) |
~1,884 |
| Lines |
~512,664 |
| Largest single file |
query.ts (~785KB) |
| Built-in tools |
~40+ |
| Slash commands |
~80+ |
| Dependencies (node_modules) |
~192 packages |
| Runtime |
Bun (compiled to Node.js >= 18 bundle) |
The Agent Pattern
THE CORE LOOP
=============
User --> messages[] --> Claude API --> response
|
stop_reason == "tool_use"?
/ \
yes no
| |
execute tools return text
append tool_result
loop back -----------------> messages[]
That is the minimal agent loop. Claude Code wraps this loop
with a production-grade harness: permissions, streaming,
concurrency, compaction, sub-agents, persistence, and MCP.
Directory Reference
src/
├── main.tsx # REPL bootstrap, 4,683 lines
├── QueryEngine.ts # SDK/headless query lifecycle engine
├── query.ts # Main agent loop (785KB, largest file)
├── Tool.ts # Tool interface + buildTool factory
├── Task.ts # Task types, IDs, state base
├── tools.ts # Tool registry, presets, filtering
├── commands.ts # Slash command definitions
├── context.ts # User input context
├── cost-tracker.ts # API cost accumulation
├── setup.ts # First-run setup flow
│
├── bridge/ # Claude Desktop / remote bridge
│ ├── bridgeMain.ts # Session lifecycle manager
│ ├── bridgeApi.ts # HTTP client
│ ├── bridgeConfig.ts # Connection config
│ ├── bridgeMessaging.ts # Message relay
│ ├── sessionRunner.ts # Process spawning
│ ├── jwtUtils.ts # JWT refresh
│ ├── workSecret.ts # Auth tokens
│ └── capacityWake.ts # Capacity-based wakeup
│
├── cli/ # CLI infrastructure
│ ├── handlers/ # Command handlers
│ └── transports/ # I/O transports (stdio, structured)
│
├── commands/ # ~80 slash commands
│ ├── agents/ # Agent management
│ ├── compact/ # Context compaction
│ ├── config/ # Settings management
│ ├── help/ # Help display
│ ├── login/ # Authentication
│ ├── mcp/ # MCP server management
│ ├── memory/ # Memory system
│ ├── plan/ # Plan mode
│ ├── resume/ # Session resume
│ ├── review/ # Code review
│ └── ... # 70+ more commands
│
├── components/ # React/Ink terminal UI
│ ├── design-system/ # Reusable UI primitives
│ ├── messages/ # Message rendering
│ ├── permissions/ # Permission dialogs
│ ├── PromptInput/ # Input field + suggestions
│ ├── LogoV2/ # Branding + welcome screen
│ ├── Settings/ # Settings panels
│ ├── Spinner.tsx # Loading indicators
│ └── ... # 40+ component groups
│
├── entrypoints/ # Application entry points
│ ├── cli.tsx # CLI main (version, help, daemon)
│ ├── sdk/ # Agent SDK (types, sessions)
│ └── mcp.ts # MCP server entry
│
├── hooks/ # React hooks
│ ├── useCanUseTool.tsx # Permission checking
│ ├── useReplBridge.tsx # Bridge connection
│ ├── notifs/ # Notification hooks
│ └── toolPermission/ # Tool permission handlers
│
├── services/ # Business logic layer
│ ├── api/ # Claude API client
│ │ ├── claude.ts # Streaming API calls
│ │ ├── errors.ts # Error categorization
│ │ └── withRetry.ts # Retry logic
│ ├── analytics/ # Telemetry + GrowthBook
│ ├── compact/ # Context compression
│ ├── mcp/ # MCP connection management
│ ├── tools/ # Tool execution engine
│ │ ├── StreamingToolExecutor.ts # Parallel tool runner
│ │ └── toolOrchestration.ts # Batch orchestration
│ ├── plugins/ # Plugin loader
│ └── settingsSync/ # Cross-device settings
│
├── state/ # Application state
│ ├── AppStateStore.ts # Store definition
│ └── AppState.tsx # React provider + hooks
│
├── tasks/ # Task implementations
│ ├── LocalShellTask/ # Bash command execution
│ ├── LocalAgentTask/ # Sub-agent execution
│ ├── RemoteAgentTask/ # Remote agent via bridge
│ ├── InProcessTeammateTask/ # In-process teammate
│ └── DreamTask/ # Background thinking
│
├── tools/ # 40+ tool implementations
│ ├── AgentTool/ # Sub-agent spawning + fork
│ ├── BashTool/ # Shell command execution
│ ├── FileReadTool/ # File reading (PDF, image, etc)
│ ├── FileEditTool/ # String-replace editing
│ ├── FileWriteTool/ # Full file creation
│ ├── GlobTool/ # File pattern search
│ ├── GrepTool/ # Content search (ripgrep)
│ ├── WebFetchTool/ # HTTP fetching
│ ├── WebSearchTool/ # Web search
│ ├── MCPTool/ # MCP tool wrapper
│ ├── SkillTool/ # Skill invocation
│ ├── AskUserQuestionTool/ # User interaction
│ └── ... # 30+ more tools
│
├── types/ # Type definitions
│ ├── message.ts # Message discriminated unions
│ ├── permissions.ts # Permission types
│ ├── tools.ts # Tool progress types
│ └── ids.ts # Branded ID types
│
├── utils/ # Utilities (largest directory)
│ ├── permissions/ # Permission rule engine
│ ├── messages/ # Message formatting
│ ├── model/ # Model selection logic
│ ├── settings/ # Settings management
│ ├── sandbox/ # Sandbox runtime adapter
│ ├── hooks/ # Hook execution
│ ├── memory/ # Memory system utils
│ ├── git/ # Git operations
│ ├── github/ # GitHub API
│ ├── bash/ # Bash execution helpers
│ ├── swarm/ # Multi-agent swarm
│ ├── telemetry/ # Telemetry reporting
│ └── ... # 30+ more util groups
│
└── vendor/ # Native module source stubs
├── audio-capture-src/ # Audio input
├── image-processor-src/ # Image processing
├── modifiers-napi-src/ # Native modifiers
└── url-handler-src/ # URL handling
Architecture Overview
┌─────────────────────────────────────────────────────────────────────┐
│ ENTRY LAYER │
│ cli.tsx ──> main.tsx ──> REPL.tsx (interactive) │
│ └──> QueryEngine.ts (headless/SDK) │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ QUERY ENGINE │
│ submitMessage(prompt) ──> AsyncGenerator<SDKMessage> │
│ │ │
│ ├── fetchSystemPromptParts() ──> assemble system prompt │
│ ├── processUserInput() ──> handle /commands │
│ ├── query() ──> main agent loop │
│ │ ├── StreamingToolExecutor ──> parallel tool execution │
│ │ ├── autoCompact() ──> context compression │
│ │ └── runTools() ──> tool orchestration │
│ └── yield SDKMessage ──> stream to consumer │
└──────────────────────────────┬──────────────────────────────────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌─────────────────┐ ┌──────────────────┐
│ TOOL SYSTEM │ │ SERVICE LAYER │ │ STATE LAYER │
│ │ │ │ │ │
│ Tool Interface │ │ api/claude.ts │ │ AppState Store │
│ ├─ call() │ │ API client │ │ ├─ permissions │
│ ├─ validate() │ │ compact/ │ │ ├─ fileHistory │
│ ├─ checkPerms() │ │ auto-compact │ │ ├─ agents │
│ ├─ render() │ │ mcp/ │ │ └─ fastMode │
│ └─ prompt() │ │ MCP protocol │ │ │
│ │ │ analytics/ │ │ React Context │
│ 40+ Built-in: │ │ telemetry │ │ ├─ useAppState │
│ ├─ BashTool │ │ tools/ │ │ └─ useSetState │
│ ├─ FileRead │ │ executor │ │ │
│ ├─ FileEdit │ │ plugins/ │ └──────────────────┘
│ ├─ Glob/Grep │ │ loader │
│ ├─ AgentTool │ │ settingsSync/ │
│ ├─ WebFetch │ │ cross-device │
│ └─ MCPTool │ │ oauth/ │
│ │ │ auth flow │
└──────────────────┘ └─────────────────┘
│ │
▼ ▼
┌──────────────────┐ ┌─────────────────┐
│ TASK SYSTEM │ │ BRIDGE LAYER │
│ │ │ │
│ Task Types: │ │ bridgeMain.ts │
│ ├─ local_bash │ │ session mgmt │
│ ├─ local_agent │ │ bridgeApi.ts │
│ ├─ remote_agent │ │ HTTP client │
│ ├─ in_process │ │ workSecret.ts │
│ ├─ dream │ │ auth tokens │
│ └─ workflow │ │ sessionRunner │
│ │ │ process spawn │
│ ID: prefix+8chr │ └─────────────────┘
│ b=bash a=agent │
│ r=remote t=team │
└──────────────────┘
Data Flow: A Single Query Lifecycle
USER INPUT (prompt / slash command)
│
▼
processUserInput() ← parse /commands, build UserMessage
│
▼
fetchSystemPromptParts() ← tools → prompt sections, CLAUDE.md memory
│
▼
recordTranscript() ← persist user message to disk (JSONL)
│
这是一个研究型代码仓库，对 Anthropic 的 Claude Code CLI 智能体的内部架构进行逆向分析和记录，涵盖其工具系统、提示词结构、遥测以及隐藏功能。