# pengchengneo/claude-code architecture

> Architecture diagram of the GitHub repository pengchengneo/claude-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pengchengneo/claude-code
- Repository: https://github.com/pengchengneo/claude-code

## Overview

#### 定位与入口
这是从 `@anthropic-ai/claude-code` source map 还原的可运行 TypeScript CLI，目标是研究 Claude Code 的本地代理、终端 UI 和受门控的内部能力。开发入口为 `src/entrypoints/cli.tsx`，主应用装配在 `src/main.tsx` 与 `src/setup.ts`；另有初始化与 MCP 入口：`src/entrypoints/init.ts`、`src/entrypoints/mcp.ts`。

#### 交互式 CLI 与状态层
CLI 使用 React/TSX 终端界面，根屏幕和 REPL 分别位于 `src/components/App.tsx`、`src/screens/REPL.tsx`。仓库内置 Ink 渲染/终端事件实现（而非仅依赖外部 UI）：`src/ink/ink.tsx`、`src/ink/renderer.ts`。会话级 UI 状态集中在 `src/state/AppState.tsx`、`src/state/AppStateStore.ts`，输入经 `src/utils/processUserInput/processUserInput.ts` 分流为文本提示、shell 输入或斜杠命令。

#### Agent 查询循环、工具与权限边界
核心控制流是：用户消息 → 查询/模型流 → 工具调用 → 权限决策 → 工具结果回注会话。查询编排的关键边界在 `src/QueryEngine.ts`、`src/query.ts`、`src/query/transitions.ts`；工具执行由 `src/services/tools/toolOrchestration.ts` 和 `src/services/tools/StreamingToolExecutor.ts` 统一调度。具体能力以工具模块实现，如 `src/tools/BashTool/BashTool.tsx`、`src/tools/FileEditTool/FileEditTool.ts`、`src/tools/AgentTool/AgentTool.tsx`。权限规则与模式在 `src/utils/permissions/permissions.ts`、`src/utils/permissions/PermissionMode.ts`，交互审批 UI 位于 `src/components/permissions/PermissionPrompt.tsx`；这是模型行为与本地文件/进程副作用之间的主要安全边界。

#### 命令、扩展与上下文持久化
斜杠命令注册/路由以 `src/commands.ts` 为中心，命令实现位于 `src/commands/`；它们改变会话、配置或调用服务，而非独立应用入口。插件、技能和 MCP 是三条扩展边界：`src/services/plugins/PluginInstallationManager.ts`、`src/skills/loadSkillsDir.ts`、`src/services/mcp/MCPConnectionManager.tsx`。本地记忆与上下文压缩分别由 `src/memdir/memdir.ts`、`src/services/compact/compact.ts`、`src/services/SessionMemory/sessionMemory.ts` 管理，以控制长会话 token 与跨会话信息复用。

#### 并发代理与远程会话
任务抽象统一本地 shell、工作流、子代理与远程代理，核心类型/生命周期在 `src/tasks/types.ts`、`src/tasks/LocalAgentTask/LocalAgentTask.tsx`、`src/tasks/RemoteAgentTask/RemoteAgentTask.tsx`。多 Agent coordinator 通过 `src/coordinator/coordinatorMode.ts` 和 `src/coordinator/workerAgent.ts` 将主代理限制为委派/通信/停止角色。远程会话由 `src/remote/RemoteSessionManager.ts`、`src/remote/SessionsWebSocket.ts` 管理；远程控制 bridge 则通过 `src/bridge/bridgeMain.ts`、`src/bridge/bridgeMessaging.ts`、`src/bridge/bridgePermissionCallbacks.ts` 同步消息、状态与审批。

#### 外部依赖、平台与功能门控
运行要求 Bun 与 Node；终端 UI 使用 React/Ink，原生能力通过本地兼容包连接，例如 `shims/color-diff-napi/index.ts`、`shims/ant-computer-use-mcp/index.ts`。网络边界包括 Claude API 客户端（`src/services/api/claude.ts`、`src/services/api/client.ts`）、OAuth（`src/services/oauth/client.ts`）、MCP server/client、WebSocket/SSE transport（`src/cli/transports/WebSocketTransport.ts`、`src/cli/transports/SSETransport.ts`），并支持 AWS Bedrock/Google Vertex 模型路径。功能可被编译开关、`USER_TYPE` 和 GrowthBook 远程实验共同限制；实验接入集中于 `src/services/analytics/growthbook.ts`，因此功能存在并不等于外部运行时可用。

Main entry points: [`src/QueryEngine.ts`](https://github.com/pengchengneo/claude-code/blob/main/src/QueryEngine.ts) (查询编排), [`src/components/App.tsx`](https://github.com/pengchengneo/claude-code/blob/main/src/components/App.tsx) (根终端界面), [`src/utils/permissions/permissions.ts`](https://github.com/pengchengneo/claude-code/blob/main/src/utils/permissions/permissions.ts) (权限策略与模式), [`src/utils/processUserInput/processUserInput.ts`](https://github.com/pengchengneo/claude-code/blob/main/src/utils/processUserInput/processUserInput.ts) (用户输入分流)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["CLI 与终端 UI"]
  node_cli["CLI 入口<br/>TypeScript CLI<br/>[cli.tsx]"]
  node_bootstrap["应用装配<br/>bootstrap<br/>[main.tsx]"]
  node_app["根终端界面<br/>React screen<br/>[App.tsx]"]
  node_repl["交互 REPL<br/>terminal screen<br/>[REPL.tsx]"]
  node_ink["内置 Ink 渲染器<br/>terminal renderer<br/>[renderer.ts]"]
  node_state["会话 UI 状态<br/>state store<br/>[AppStateStore.ts]"]
  node_input["用户输入分流<br/>input router"]
  node_commands["斜杠命令<br/>command router<br/>[commands.ts]"]
end

subgraph group_agent["Agent 执行与安全"]
  node_query{{"查询编排<br/>agent loop<br/>[QueryEngine.ts]"}}
  node_tools["工具编排<br/>tool orchestrator"]
  node_executor["流式工具执行<br/>tool executor"]
  node_localtools["本地副作用工具<br/>[BashTool.tsx]"]
  node_permissions{{"权限策略与模式<br/>security policy<br/>[permissions.ts]"}}
  node_prompt["权限审批界面<br/>approval UI"]
end

subgraph group_extension["扩展、记忆与远程"]
  node_memory[("会话记忆与压缩<br/>context persistence<br/>[sessionMemory.ts]")]
  node_plugins["插件与技能<br/>extension loader"]
  node_mcp["MCP 连接管理<br/>MCP client manager"]
  node_tasks["本地与远程任务<br/>task lifecycle<br/>[types.ts]"]
  node_coordinator["多 Agent 协调器<br/>agent coordinator<br/>[coordinatorMode.ts]"]
  node_remote["远程会话管理<br/>remote session manager"]
  node_bridge["远程控制 Bridge<br/>bridge runtime<br/>[bridgeMain.ts]"]
end

subgraph group_external["外部平台与门控"]
  node_api["Claude API 客户端<br/>model API client<br/>[claude.ts]"]
  node_oauth["OAuth 客户端<br/>authentication client<br/>[client.ts]"]
  node_growthbook["实验与功能门控<br/>feature gate<br/>[growthbook.ts]"]
  node_transport["WebSocket / SSE 传输<br/>network transport"]
end

node_cli -->|"启动"| node_bootstrap
node_bootstrap -->|"装配"| node_app
node_app -->|"呈现"| node_repl
node_app -->|"读取与更新"| node_state
node_app -->|"终端渲染"| node_ink
node_repl -->|"提交输入"| node_input
node_input -->|"斜杠命令"| node_commands
node_input -->|"文本提示"| node_query
node_commands -->|"修改会话或配置"| node_state
node_query -->|"模型请求流"| node_api
node_query -->|"工具调用"| node_tools
node_query -->|"读取与保存上下文"| node_memory
node_tools -->|"调度"| node_executor
node_executor -->|"请求授权"| node_permissions
node_permissions -->|"需要交互时"| node_prompt
node_prompt -->|"审批结果"| node_permissions
node_permissions -->|"授权执行"| node_localtools
node_executor -->|"工具结果回注"| node_query
node_query -->|"创建任务"| node_tasks
node_coordinator -->|"委派 worker"| node_tasks
node_tasks -->|"远程代理任务"| node_remote
node_remote -->|"同步控制状态"| node_bridge
node_bridge -->|"网络消息"| node_transport
node_plugins -->|"扩展能力"| node_mcp
node_mcp -->|"提供工具"| node_tools
node_oauth -->|"认证"| node_api
node_growthbook -.->|"门控能力"| node_query
node_growthbook -.->|"门控扩展"| node_plugins

click node_cli "https://github.com/pengchengneo/claude-code/blob/main/src/entrypoints/cli.tsx"
click node_bootstrap "https://github.com/pengchengneo/claude-code/blob/main/src/main.tsx"
click node_app "https://github.com/pengchengneo/claude-code/blob/main/src/components/App.tsx"
click node_repl "https://github.com/pengchengneo/claude-code/blob/main/src/screens/REPL.tsx"
click node_ink "https://github.com/pengchengneo/claude-code/blob/main/src/ink/renderer.ts"
click node_state "https://github.com/pengchengneo/claude-code/blob/main/src/state/AppStateStore.ts"
click node_input "https://github.com/pengchengneo/claude-code/blob/main/src/utils/processUserInput/processUserInput.ts"
click node_commands "https://github.com/pengchengneo/claude-code/blob/main/src/commands.ts"
click node_query "https://github.com/pengchengneo/claude-code/blob/main/src/QueryEngine.ts"
click node_tools "https://github.com/pengchengneo/claude-code/blob/main/src/services/tools/toolOrchestration.ts"
click node_executor "https://github.com/pengchengneo/claude-code/blob/main/src/services/tools/StreamingToolExecutor.ts"
click node_localtools "https://github.com/pengchengneo/claude-code/blob/main/src/tools/BashTool/BashTool.tsx"
click node_permissions "https://github.com/pengchengneo/claude-code/blob/main/src/utils/permissions/permissions.ts"
click node_prompt "https://github.com/pengchengneo/claude-code/blob/main/src/components/permissions/PermissionPrompt.tsx"
click node_memory "https://github.com/pengchengneo/claude-code/blob/main/src/services/SessionMemory/sessionMemory.ts"
click node_plugins "https://github.com/pengchengneo/claude-code/blob/main/src/services/plugins/PluginInstallationManager.ts"
click node_mcp "https://github.com/pengchengneo/claude-code/blob/main/src/services/mcp/MCPConnectionManager.tsx"
click node_tasks "https://github.com/pengchengneo/claude-code/blob/main/src/tasks/types.ts"
click node_coordinator "https://github.com/pengchengneo/claude-code/blob/main/src/coordinator/coordinatorMode.ts"
click node_remote "https://github.com/pengchengneo/claude-code/blob/main/src/remote/RemoteSessionManager.ts"
click node_bridge "https://github.com/pengchengneo/claude-code/blob/main/src/bridge/bridgeMain.ts"
click node_api "https://github.com/pengchengneo/claude-code/blob/main/src/services/api/claude.ts"
click node_oauth "https://github.com/pengchengneo/claude-code/blob/main/src/services/oauth/client.ts"
click node_growthbook "https://github.com/pengchengneo/claude-code/blob/main/src/services/analytics/growthbook.ts"
click node_transport "https://github.com/pengchengneo/claude-code/blob/main/src/cli/transports/WebSocketTransport.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_bootstrap,node_app,node_repl,node_ink,node_state,node_input,node_commands toneBlue
class node_query,node_tools,node_executor,node_localtools,node_permissions,node_prompt toneAmber
class node_memory,node_plugins,node_mcp,node_tasks,node_coordinator,node_remote,node_bridge toneMint
class node_api,node_oauth,node_growthbook,node_transport toneRose
```

## Components

### CLI 与终端 UI

- [CLI 入口](https://github.com/pengchengneo/claude-code/blob/main/src/entrypoints/cli.tsx): TypeScript CLI · `src/entrypoints/cli.tsx`
- [应用装配](https://github.com/pengchengneo/claude-code/blob/main/src/main.tsx): bootstrap · `src/main.tsx`
- [根终端界面](https://github.com/pengchengneo/claude-code/blob/main/src/components/App.tsx): React screen · `src/components/App.tsx`
- [交互 REPL](https://github.com/pengchengneo/claude-code/blob/main/src/screens/REPL.tsx): terminal screen · `src/screens/REPL.tsx`
- [内置 Ink 渲染器](https://github.com/pengchengneo/claude-code/blob/main/src/ink/renderer.ts): terminal renderer · 实现终端渲染与事件处理。 · `src/ink/renderer.ts`
- [会话 UI 状态](https://github.com/pengchengneo/claude-code/blob/main/src/state/AppStateStore.ts): state store · `src/state/AppStateStore.ts`
- [用户输入分流](https://github.com/pengchengneo/claude-code/blob/main/src/utils/processUserInput/processUserInput.ts): input router · `src/utils/processUserInput/processUserInput.ts`
- [斜杠命令](https://github.com/pengchengneo/claude-code/blob/main/src/commands.ts): command router · `src/commands.ts`

### Agent 执行与安全

- [查询编排](https://github.com/pengchengneo/claude-code/blob/main/src/QueryEngine.ts): agent loop · 协调模型流、状态转换与工具结果回注。 · `src/QueryEngine.ts`
- [工具编排](https://github.com/pengchengneo/claude-code/blob/main/src/services/tools/toolOrchestration.ts): tool orchestrator · `src/services/tools/toolOrchestration.ts`
- [流式工具执行](https://github.com/pengchengneo/claude-code/blob/main/src/services/tools/StreamingToolExecutor.ts): tool executor · `src/services/tools/StreamingToolExecutor.ts`
- [本地副作用工具](https://github.com/pengchengneo/claude-code/blob/main/src/tools/BashTool/BashTool.tsx): Bash / file / agent tools · `src/tools/BashTool/BashTool.tsx`
- [权限策略与模式](https://github.com/pengchengneo/claude-code/blob/main/src/utils/permissions/permissions.ts): security policy · 模型调用本地文件和进程前的安全边界。 · `src/utils/permissions/permissions.ts`
- [权限审批界面](https://github.com/pengchengneo/claude-code/blob/main/src/components/permissions/PermissionPrompt.tsx): approval UI · `src/components/permissions/PermissionPrompt.tsx`

### 扩展、记忆与远程

- [会话记忆与压缩](https://github.com/pengchengneo/claude-code/blob/main/src/services/SessionMemory/sessionMemory.ts): context persistence · 复用跨会话信息并控制长会话 token。 · `src/services/SessionMemory/sessionMemory.ts`
- [插件与技能](https://github.com/pengchengneo/claude-code/blob/main/src/services/plugins/PluginInstallationManager.ts): extension loader · `src/services/plugins/PluginInstallationManager.ts`
- [MCP 连接管理](https://github.com/pengchengneo/claude-code/blob/main/src/services/mcp/MCPConnectionManager.tsx): MCP client manager · `src/services/mcp/MCPConnectionManager.tsx`
- [本地与远程任务](https://github.com/pengchengneo/claude-code/blob/main/src/tasks/types.ts): task lifecycle · 统一 shell、工作流、子代理和远程代理任务。 · `src/tasks/types.ts`
- [多 Agent 协调器](https://github.com/pengchengneo/claude-code/blob/main/src/coordinator/coordinatorMode.ts): agent coordinator · 限制主代理执行委派、通信与停止。 · `src/coordinator/coordinatorMode.ts`
- [远程会话管理](https://github.com/pengchengneo/claude-code/blob/main/src/remote/RemoteSessionManager.ts): remote session manager · `src/remote/RemoteSessionManager.ts`
- [远程控制 Bridge](https://github.com/pengchengneo/claude-code/blob/main/src/bridge/bridgeMain.ts): bridge runtime · 同步远程消息、状态和审批。 · `src/bridge/bridgeMain.ts`

### 外部平台与门控

- [Claude API 客户端](https://github.com/pengchengneo/claude-code/blob/main/src/services/api/claude.ts): model API client · `src/services/api/claude.ts`
- [OAuth 客户端](https://github.com/pengchengneo/claude-code/blob/main/src/services/oauth/client.ts): authentication client · `src/services/oauth/client.ts`
- [实验与功能门控](https://github.com/pengchengneo/claude-code/blob/main/src/services/analytics/growthbook.ts): feature gate · 由编译开关、用户类型和远程实验共同限制。 · `src/services/analytics/growthbook.ts`
- [WebSocket / SSE 传输](https://github.com/pengchengneo/claude-code/blob/main/src/cli/transports/WebSocketTransport.ts): network transport · `src/cli/transports/WebSocketTransport.ts`

## Connections

- CLI 入口 → 应用装配: 启动
- 应用装配 → 根终端界面: 装配
- 根终端界面 → 交互 REPL: 呈现
- 根终端界面 → 会话 UI 状态: 读取与更新
- 根终端界面 → 内置 Ink 渲染器: 终端渲染
- 交互 REPL → 用户输入分流: 提交输入
- 用户输入分流 → 斜杠命令: 斜杠命令
- 用户输入分流 → 查询编排: 文本提示
- 斜杠命令 → 会话 UI 状态: 修改会话或配置
- 查询编排 → Claude API 客户端: 模型请求流
- 查询编排 → 工具编排: 工具调用
- 查询编排 → 会话记忆与压缩: 读取与保存上下文
- 工具编排 → 流式工具执行: 调度
- 流式工具执行 → 权限策略与模式: 请求授权
- 权限策略与模式 → 权限审批界面: 需要交互时
- 权限审批界面 → 权限策略与模式: 审批结果
- 权限策略与模式 → 本地副作用工具: 授权执行
- 流式工具执行 → 查询编排: 工具结果回注
- 查询编排 → 本地与远程任务: 创建任务
- 多 Agent 协调器 → 本地与远程任务: 委派 worker
- 本地与远程任务 → 远程会话管理: 远程代理任务
- 远程会话管理 → 远程控制 Bridge: 同步控制状态
- 远程控制 Bridge → WebSocket / SSE 传输: 网络消息
- 插件与技能 → MCP 连接管理: 扩展能力
- MCP 连接管理 → 工具编排: 提供工具
- OAuth 客户端 → Claude API 客户端: 认证
- 实验与功能门控 → 查询编排: 门控能力
- 实验与功能门控 → 插件与技能: 门控扩展