Claude Code Architecture Study
A detailed study of Claude Code’s CLI agent loop, tools, permissions, context handling, and multi-agent architecture.
The README describes input validation, permission rules, interactive approval, tool-specific authorization, and some path sandboxing, supporting moderate scores for least privilege, confirmation, and control of external effects. Its query lifecycle also maps prompts, disk transcripts, API traffic, and tool results. Deductions apply because default rules, implementation evidence, and data-retention or deletion policies are absent. JWTs, work secrets, telemetry, full tool-input capture, and transcript persistence are mentioned without corresponding credential-protection details. No lockfile, audit, update process, or vulnerability mitigation supports dependency security. fileHistory and worktrees imply limited recovery, but no explicit rollback procedure is documented. Attribution only refers generally to public online material and community discussion without claim-level citations.
The directory map, architecture diagrams, tool inventory, and lifecycle are broadly consistent with one another. Input validation, error categorization, retries, and permission-denial results are mentioned. Deductions apply because no actual code, tests, or configuration are included to verify these descriptions. Bun, Node.js >=18, and an approximate package count provide only thin dependency-availability guidance without a reproducible dependency set or installation path. Error categories, retry limits, user-facing messages, and unrecoverable-failure behavior are not demonstrated.
The material identifies developers studying CLI Agent architecture as its audience and covers interactive, headless SDK, local, remote, worktree, and multi-agent scenarios. Permission matching, slash-command parsing, and tool lifecycles give triggers some precision. Deductions apply because the boundary between research material and a usable Agent product is unclear, and the README does not distinguish consistently between available, inferred, unreleased, or feature-gated capabilities. Environment guidance stops at Bun, a Node version, and runtime shapes, omitting operating-system, configuration, authentication, and compatibility requirements.
The README is thoroughly organized into navigable directory, architecture, data-flow, tool, permission, and multi-agent sections, justifying full marks for information architecture. Names are mostly stable across diagrams, but approximate counts, aliases, and the lack of source-file verification reduce certainty. Numerous structural illustrations are present, but there are no operational examples or FAQ. The disclaimer states research-only and noncommercial terms, yet it is not a clearly identified standard license and license metadata is unknown. Installation notes, release versioning, and a changelog are absent. Maintenance responsibility is limited to a vague invitation to contact the owner and a promise of future sharing, with no named maintainer, channel, or response policy.
The architecture diagrams, lifecycle, tool inventory, and permission flow are usable for understanding a complex CLI Agent and add meaningful value beyond a minimal agent-loop description. Deductions apply because no runnable walkthrough, sample interaction, or task-oriented output demonstrates practical effectiveness. Cost is only implied by a cost-tracker filename; model, API, telemetry, dependency-maintenance, and deployment costs are neither quantified nor weighed against benefits.
Some claims map to listed filenames, directories, and components, providing limited internal traceability. Deductions apply because the supplied evidence contains only the README, with no code, tests, history, or report bodies to substantiate it. Public references and community discussions are not cited specifically, preventing cross-source corroboration. Claims about telemetry, undercover mode, remote control, and future plans are presented confidently without systematically distinguishing direct observation, third-party reporting, and inference.
- This is a static assessment of the supplied README only; no code was executed, and the claimed source size, tool counts, and architecture were not independently verified.
- The repository describes transcript persistence, telemetry, JWTs, work secrets, and optional capture of complete tool inputs. Verify default collection, retention, access controls, and deletion behavior before processing source code, credentials, or personal data.
- Shell, file-writing, network, MCP, remote-agent, and multi-agent tools can have broad external effects. Confirm default permissions, sandbox boundaries, remotely delivered configuration changes, and denial behavior in the actual implementation.
- The noncommercial disclaimer is not a substitute for a clear license. Obtain explicit authorization before copying, modifying, distributing, or adopting the material commercially.
- Claims about hidden features, concealed employee authorship, non-optional telemetry, and future product plans lack claim-level sources in the supplied evidence and should be treated as independently unverified research conclusions.
What does this agent do, and when should you use it?
This is a learning and technical-research repository about Claude Code’s CLI agent architecture, not a documented standalone agent distribution ready for deployment. It describes a streaming execution model centered on query.ts and QueryEngine.ts: accept user input, call the Claude API, execute requested tools, and append their results to the message loop. The material covers more than 40 built-in tools, roughly 80 slash commands, permission rules, context compaction, session persistence, MCP, remote bridging, and sub-agent execution. Documented interfaces include a React/Ink terminal UI, a headless SDK query engine, and an MCP entry point, with state and transcripts stored primarily on the local filesystem. The repository also contains English, Chinese, Japanese, and Korean reports about telemetry, feature flags, remote controls, and prospective functionality. Because reproducible installation, build, credential, and first-run instructions are absent, it is best evaluated as an architecture reference rather than an adoptable production release.
In the documented lifecycle, processUserInput() parses prompts and slash commands, while fetchSystemPromptParts() assembles tool sections and CLAUDE.md memory before query() streams a response from the Claude API. When the model emits tool_use, StreamingToolExecutor separates concurrency-safe work from serial work, and canUseTool() applies PreToolUse hooks, allow or deny rules, an interactive prompt, and tool-specific permission checks. Approved calls run through tool.call(); their tool_result values are appended to messages[] and sent through the loop again. The inventory includes BashTool, FileReadTool, FileEditTool, FileWriteTool, GlobTool, GrepTool, WebFetchTool, WebSearchTool, AgentTool, and MCPTool. The study also describes autoCompact, snipCompact, and contextCollapse for context management, plus append-only JSONL transcripts, session resumption, and session forking. AgentTool, SendMessageTool, TeamCreateTool, and task commands support local, remote, in-process, and worktree-isolated agent modes, while bridgeMain.ts and related modules relay remote sessions. The repository itself primarily produces architecture documentation and multilingual analysis; it does not document a verified standalone agent workflow that readers can install and invoke.
- An engineer designing a coding agent can study the complete loop from Claude API streaming through tool execution and tool-result feedback.
- A CLI developer handling risky operations can examine the layered authorization flow across hooks, matching rules, user prompts, and tool-level checks.
- A team building long-running assistant sessions can evaluate the documented autoCompact, snipCompact, contextCollapse, and JSONL recovery patterns.
- A technical lead assessing multi-agent designs can compare in-process teammates, forked children, remote agents, and worktree isolation.
- A security researcher examining Claude Code can use the quadrilingual reports on telemetry, feature flags, undercover behavior, and remote configuration.
What are this agent's strengths and limitations?
- Maps the full path from entry points and the query engine to tools, services, and application state, using concrete filenames and class names.
- Organizes production-agent concerns into 12 progressive mechanisms spanning planning, sub-agents, compaction, background tasks, teams, and worktree isolation.
- Documents the permission decision chain, tool lifecycle, and concurrent execution model in enough detail to support security-oriented design study.
- Provides the same family of deep-dive reports in English, Chinese, Japanese, and Korean for multilingual engineering teams.
- Commercial use is explicitly prohibited, excluding adoption in commercial products and revenue-generating work.
- There are no reproducible installation, build, credential, or first-run instructions, leaving deployability unverified.
- The studied core path is tied to Claude Code and the Claude API, with no demonstrated multi-provider portability.
- The README contains research claims about hidden, future, and unreleased features without independent verification evidence or stability guarantees in the supplied material.
- The repository license is listed as unknown while separate non-commercial and intellectual-property restrictions are asserted, creating an unclear adoption boundary.
How do you install or deploy this agent?
The source does not provide copyable clone-to-install, dependency installation, build, or launch commands. It also omits the required Bun version, package-manager procedure, and Claude API credential configuration. The only runtime details supplied are Bun and a bundle compiled for Node.js >= 18, which are insufficient to establish a reproducible installation. The repository therefore cannot be verified from the supplied material as an installable standalone agent.
How do you use this agent?
Use it as a structured architecture study: begin with The Agent Pattern and Architecture Overview, then consult the Tool System, Permission System, Context Management, MCP, Session Persistence, and Sub-Agent sections for individual mechanisms. The deeper reports are organized under docs/en, docs/zh, docs/ja, and docs/ko. For actual execution, the source lacks build commands, Claude API credential setup, an entry-point invocation, and a first working example, so no accurate runnable procedure can be given.