Repository: claude-code-best/claude-code

Stars: 16135

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview Copy Chapter

This is a reverse-engineered / decompiled version of Anthropic's official Claude Code CLI tool. The goal is to restore core functionality while trimming secondary capabilities. Many modules are stubbed or feature-flagged off. TypeScript strict mode is enforced（见 Working with This Codebase 段的 tsc 要求）。

Git Commit Message Convention Copy Chapter

使用 Conventional Commits 规范：

<type>: <描述>

常见 type：feat、fix、docs、chore、refactor

示例：
- feat: 添加模型 1M 上下文切换
- fix: 修复初次登陆的校验问题
- chore: remove prefetchOfficialMcpUrls call on startup

Commands Copy Chapter

Install dependencies

bun install
Dev mode (runs cli.tsx with MACRO defines injected via -d flags)

bun run dev
Dev mode with debugger (set BUN_INSPECT=9229 to pick port)

bun run dev:inspect
Pipe mode

echo "say hello" | bun run src/entrypoints/cli.tsx -p
Build (code splitting, outputs dist/cli.js + chunk files)

bun run build
Build with Vite (alternative build pipeline)

bun run build:vite
Test

bun test                  # run all tests (3066 tests / 205 files / 0 fail)
bun test src/utils/__tests__/hash.test.ts   # run single file
bun test --coverage       # with coverage report
Lint & Format (Biome)

bun run lint              # check only
bun run lint:fix          # auto-fix
bun run format            # format all src/
Health check

bun run health
Check unused exports

bun run check:unused
bun run typecheck
Remote Control Server

bun run rcs
Docs dev server (Mintlify)

bun run docs:dev

详细的测试规范、覆盖状态和改进计划见 docs/testing-spec.md。

Architecture Copy Chapter

Runtime & Build Copy Section

- Runtime: Bun (not Node.js). All imports, builds, and execution use Bun APIs.
- Build: build.ts 执行 Bun.build() with splitting: true，入口 src/entrypoints/cli.tsx，输出 dist/cli.js + chunk files。Build 默认启用 19 个 feature（见下方 Feature Flag 段）。构建后自动替换 import.meta.require 为 Node.js 兼容版本（产物 bun/node 都可运行）。
- Dev mode: scripts/dev.ts 通过 Bun -d flag 注入 MACRO.* defines，运行 src/entrypoints/cli.tsx。默认启用全部 feature。
- Module system: ESM ("type": "module"), TSX with react-jsx transform.
- Monorepo: Bun workspaces — 15 个 workspace packages + 若干辅助目录 in packages/ resolved via workspace:*。
- Lint/Format: Biome (biome.json)。bun run lint / bun run lint:fix / bun run format。
- Defines: 集中管理在 scripts/defines.ts。当前版本 2.1.888。
- CI: GitHub Actions — ci.yml（构建+测试）、release-rcs.yml（RCS 发布）、update-contributors.yml（自动更新贡献者）。

Entry & Bootstrap Copy Section

1. src/entrypoints/cli.tsx (373 行) — True entrypoint。main() 函数按优先级处理多条快速路径：
- --version / -v — 零模块加载
- --dump-system-prompt — feature-gated (DUMP_SYSTEM_PROMPT)
- --claude-in-chrome-mcp / --chrome-native-host
- --computer-use-mcp — 独立 MCP server 模式
- --daemon-worker=<kind> — feature-gated (DAEMON)
- remote-control / rc / remote / sync / bridge — feature-gated (BRIDGE_MODE)
- daemon [subcommand] — feature-gated (DAEMON)
- ps / logs / attach / kill / --bg — feature-gated (BG_SESSIONS)
- new / list / reply — Template job commands
- environment-runner / self-hosted-runner — BYOC runner
- --tmux + --worktree 组合
- 默认路径：加载 main.tsx 启动完整 CLI
2. src/main.tsx (~6981 行) — Commander.js CLI definition。注册大量 subcommands：mcp (serve/add/remove/list...)、server、ssh、open、auth、plugin、agents、auto-mode、doctor、update 等。主 .action() 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
3. src/entrypoints/init.ts — One-time initialization (telemetry, config, trust dialog)。

Core Loop Copy Section

- src/query.ts — The main API query function. Sends messages to Claude API, handles streaming responses, processes tool calls, and manages the conversation turn loop.
- src/QueryEngine.ts — Higher-level orchestrator wrapping query(). Manages conversation state, compaction, file history snapshots, attribution, and turn-level bookkeeping. Used by the REPL screen.
- src/screens/REPL.tsx — The interactive REPL screen (React/Ink component). Handles user input, message display, tool permission prompts, and keyboard shortcuts.

API Layer Copy Section

- src/services/api/claude.ts — Core API client. Builds request params (system prompt, messages, tools, betas), calls the Anthropic SDK streaming endpoint, and processes BetaRawMessageStreamEvent events.
- 7 providers: firstParty (Anthropic direct), bedrock (AWS), vertex (Google Cloud), foundry, openai, gemini, grok (xAI)。
- Provider selection in src/utils/model/providers.ts。优先级：modelType 参数 > 环境变量 > 默认 firstParty。

Tool System Copy Section

- src/Tool.ts — Tool interface definition (Tool type) and utilities (findToolByName, toolMatchesName).
- src/tools.ts (392 行) — Tool registry. Assembles the tool list; tools are imported from @claude-code-best/builtin-tools package. Some tools are conditionally loaded via feature() flags or process.env.USER_TYPE.
- packages/builtin-tools/src/tools/ — 59 个子目录（含 shared/testing 等工具目录），通过 @claude-code-best/builtin-tools 包导出。主要分类：
- 文件操作: FileEditTool, FileReadTool, FileWriteTool, GlobTool, GrepTool
- Shell/执行: BashTool, PowerShellTool, REPLTool
- Agent 系统: AgentTool, TaskCreateTool, TaskUpdateTool, TaskListTool, TaskGetTool
- 规划: EnterPlanModeTool, ExitPlanModeV2Tool, VerifyPlanExecutionTool
- Web/MCP: WebFetchTool, WebSearchTool, MCPTool, McpAuthTool
- 调度: CronCreateTool, CronDeleteTool, CronListTool
- 其他: LSPTool, ConfigTool, SkillTool, EnterWorktreeTool, ExitWorktreeTool 等

UI Layer (Ink) Copy Section

- src/ink.ts — Ink render wrapper with ThemeProvider injection.
- packages/@ant/ink/ — Custom Ink framework（forked/internal），包含 components、core、hooks、keybindings、theme、utils。注意：不是 src/ink/。
- src/components/ — 149 个组件目录/文件，渲染于终端 Ink 环境中。关键组件：
- App.tsx — Root provider (AppState, Stats, FpsMetrics)
- Messages.tsx / MessageRow.tsx — Conversation message rendering
- PromptInput/ — User input handling
- permissions/ — Tool permission approval UI
- design-system/ — 复用 UI 组件（Dialog, FuzzyPicker, ProgressBar, ThemeProvider 等）
- Components use React Compiler runtime (react/compiler-runtime) — decompiled output has _c() memoization calls throughout.

State Management Copy Section

- src/state/AppState.tsx — Central app state type and context provider. Contains messages, tools, permissions, MCP connections, etc.
- src/state/AppStateStore.ts — Default state and store factory.
- src/state/store.ts — Zustand-style store for AppState (createStore).
- src/state/selectors.ts — State selectors.
- src/bootstrap/state.ts — Module-level singletons for session-global state (session ID, CWD, project root, token counts, model overrides, client type, permission mode).

Workspace Packages Copy Section

| Package | 说明 |
|---------|------|
| packages/@ant/ink/ | Forked Ink 框架（components、hooks、keybindings、theme） |
| packages/@ant/computer-use-mcp/ | Computer Use MCP server（截图/键鼠/剪贴板/应用管理） |
| packages/@ant/computer-use-input/ | 键鼠模拟（dispatcher + darwin/win32/linux backend） |
| packages/@ant/computer-use-swift/ | 截图 + 应用管理（dispatcher + per-platform backend） |
| packages/@ant/claude-for-chrome-mcp/ | Chrome 浏览器控制（通过 --chrome 启用） |
| packages/@ant/model-provider/ | Model provider 抽象层 |
| packages/builtin-tools/ | 内置工具集（60 个 tool 实现，通过 @claude-code-best/builtin-tools 导出） |
| packages/agent-tools/ | Agent 工具集 |
| packages/cc-knowledge/ | Claude Code 知识库（非 workspace 包） |
| packages/langfuse-dashboard/ | Langfuse 可观测性面板（非 workspace 包） |
| packages/mcp-client/ | MCP 客户端库 |
| packages/mcp-server/ | MCP 服务端库（非 workspace 包） |
| packages/remote-control-server/ | 自托管 Remote Control Server（Docker 部署，含 Web UI） |
| packages/swarm/ | Swarm 解耦模块（非 workspace 包） |
| packages/shell/ | Shell 抽象（非 workspace 包） |
| packages/audio-capture-napi/ | 原生音频捕获（已恢复） |
| packages/color-diff-napi/ | 颜色差异计算（完整实现，11 tests） |
| packages/image-processor-napi/ | 图像处理（已恢复） |
| packages/modifiers-napi/ | 键盘修饰键检测（stub） |
| packages/url-handler-napi/ | URL scheme 处理（stub） |

Bridge / Remote Control Copy Section

- src/bridge/ (~38 files) — Remote Control / Bridge 模式。feature-gated by BRIDGE_MODE。包含 bridge API、会话管理、JWT 认证、消息传输、权限回调等。Entry: bridgeMain.ts。
- packages/remote-control-server/ — 自托管 RCS，支持 Docker 部署，含 Web UI 控制面板。通过 bun run rcs 启动。
- CLI 快速路径: claude remote-control / claude rc / claude bridge。
- 详见 docs/features/remote-control-self-hosting.md。

Daemon Mode Copy Section

- src/daemon/ — Daemon 模式（长驻 supervisor）。feature-gated by DAEMON。包含 main.ts（entry）和 workerRegistry.ts（worker 管理）。

Context & System Prompt Copy Section

- src/context.ts — Builds system/user context for the API call (git status, date, CLAUDE.md contents, memory files).
- src/utils/claudemd.ts — Discovers and loads CLAUDE.md files from project hierarchy.

Feature Flag System Copy Section

Feature flags control which functionality is enabled at runtime. 代码中统一通过 import { feature } from 'bun:bundle' 导入，调用 feature('FLAG_NAME') 返回 boolean。

启用方式: 环境变量 FEATURE_<FLAG_NAME>=1。例如 FEATURE_BUDDY=1 bun run dev。

Build 默认 features（19 个，见 build.ts）:
- 基础: BUDDY, TRANSCRIPT_CLASSIFIER, BRIDGE_MODE, AGENT_TRIGGERS_REMOTE, CHICAGO_MCP, VOICE_MODE
- 统计/缓存: SHOT_STATS, PROMPT_CACHE_BREAK_DETECTION, TOKEN_BUDGET
- P0 本地: AGENT_TRIGGERS, ULTRATHINK, BUILTIN_EXPLORE_PLAN_AGENTS, LODESTONE
- P1 API 依赖: EXTRACT_MEMORIES, VERIFICATION_AGENT, KAIROS_BRIEF, AWAY_SUMMARY, ULTRAPLAN
- P2: DAEMON

Dev mode 默认: 全部启用（见 scripts/dev.ts）。

类型声明: src/types/internal-modules.d.ts 中声明了 bun:bundle 模块的 feature 函数签名。

新增功能的正确做法: 保留 import { feature } from 'bun:bundle' + feature('FLAG_NAME') 的标准模式，在运行时通过环境变量或配置控制，不要绕过 feature flag 直接 import。

Multi-API 兼容层 Copy Section

支持 OpenAI、Gemini、Grok 三种第三方 API，通过 /login 命令配置，均采用流适配器模式转为 Anthropic 内部格式。详见各兼容层的 docs 文档。

Stubbed/Deleted Modules Copy Section

| Module | Status |
|--------|--------|
| Computer Use (@ant/*) | Restored — macOS + Windows + Linux（后端完整度不一） |
| *-napi packages | audio-capture-napi、image-processor-napi 已恢复；color-diff-napi 完整；modifiers-napi、url-handler-napi 仍为 stub |
| Voice Mode | Restored — Push-to-Talk 语音输入（需 Anthropic OAuth） |
| OpenAI/Gemini/Grok 兼容层 | Restored |
| Remote Control Server | Restored — 自托管 RCS + Web UI |
| Analytics / GrowthBook / Sentry | Empty implementations |
| Magic Docs / LSP Server | Removed |
| Plugins / Marketplace | Removed |
| MCP OAuth | Simplified |

Key Type Files Copy Section

- src/types/global.d.ts — Declares MACRO, BUILD_TARGET, BUILD_ENV and internal Anthropic-only identifiers.
- src/types/internal-modules.d.ts — Type declarations for bun:bundle, bun:ffi, @anthropic-ai/mcpb.
- src/types/message.ts — Message type hierarchy (UserMessage, AssistantMessage, SystemMessage, etc.).
- src/types/permissions.ts — Permission mode and result types.

Testing Copy Chapter

- 框架: bun:test（内置断言 + mock）
- 当前状态: 3066 tests / 205 files / 0 fail
- 单元测试: 就近放置于 src//__tests__/，文件名 <module>.test.ts
- 集成测试: tests/integration/ — 4 个文件（cli-arguments, context-build, message-pipeline, tool-chain）
- 共享 mock/fixture: tests/mocks/（api-responses, file-system, fixtures/）
- 命名: describe("functionName") + test("behavior description")，英文
- 包测试: packages/ 下各包也有独立测试（如 color-diff-napi 11 tests）

Mock 使用规范 Copy Section

只 mock 有副作用的依赖链，不 mock 纯函数/纯数据模块。

被迫 mock 的根源：log.ts / debug.ts → bootstrap/state.ts（模块级 realpathSync / randomUUID 副作用）。必须 mock 的模块：log.ts、debug.ts、bun:bundle、settings/settings.js、config.ts、auth.ts、第三方网络库。

不要 mock：纯函数模块（errors.ts、stringUtils.js）、mock 值与真实实现相同的模块、mock 路径与实际 import 不匹配的模块。

路径规则：统一用 .ts 扩展名 + src/* 别名路径，禁止双重 mock 同一模块。

类型检查 Copy Section

项目使用 TypeScript strict 模式，tsc 必须零错误。每次修改后运行：

bun run typecheck          # equivalent to bun run typecheck

类型规范：
- 生产代码禁止 as any；测试文件中 mock 数据可用 as any
- 类型不匹配优先用 as unknown as SpecificType 双重断言，或补充 interface
- 未知结构对象用 Record<string, unknown> 替代 any
- 联合类型用类型守卫（type guard）收窄，不要强转
- msg.request 属性访问：const req = msg.request as Record<string, unknown>
- Ink color prop：用 as keyof Theme 而非 as any

Working with This Codebase Copy Chapter

- tsc must pass — bun run typecheck 必须零错误，任何修改都不能引入新的类型错误。
- Feature flags — 默认全部关闭（feature() 返回 false）。Dev/build 各有自己的默认启用列表。不要在 cli.tsx 中重定义 feature 函数。
- React Compiler output — Components have decompiled memoization boilerplate (const $ = _c(N)). This is normal.
- bun:bundle import — import { feature } from 'bun:bundle' 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。feature() 只能直接用在 if 语句或三元表达式的条件位置（Bun 编译器限制），不能赋值给变量、不能放在箭头函数体里、不能作为 && 链的一部分。正确：if (feature('X')) {} 或 feature('X') ? a : b。
- src/ path alias — tsconfig maps src/ to ./src/. Imports like import { ... } from 'src/utils/...' are valid.
- MACRO defines — 集中管理在 scripts/defines.ts。Dev mode 通过 bun -d 注入，build 通过 Bun.build({ define }) 注入。修改版本号等常量只改这个文件。
- 构建产物兼容 Node.js — build.ts 会自动后处理 import.meta.require，产物可直接用 node dist/cli.js 运行。
- Biome 配置 — 大量 lint 规则被关闭（decompiled 代码不适合严格 lint）。.tsx 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。
- Ink 框架在 packages/@ant/ink/ — 不是 src/ink/（该目录不存在）。Ink 相关的组件、hooks、keybindings 都在 packages 中。
- Provider 优先级 — modelType 参数 > 环境变量 > 默认 firstParty。新增 provider 需在 src/utils/model/providers.ts 注册。

README.md Copy Chapter

Claude Code Best V5 (CCB)


Which Claude do you like? The open source one is the best.

牢 A (Anthropic) 官方 Claude Code CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现 (问就是老佛爷已经付过钱了)。虽然很难绷, 但是它叫做 CCB(踩踩背)... 而且, 我们实现了企业版或者需要登陆 Claude 账号才能使用的特性, 实现技术普惠

文档在这里, 支持投稿 PR | 留影文档在这里 | Discord 群组

| 特性 | 说明 | 文档 |
|------|------|------|
| Claude 群控技术 | Pipe IPC 多实例协作：同机 main/sub 自动编排 + LAN 跨机器零配置发现与通讯，/pipes 选择面板 + Shift+↓ 交互 + 消息广播路由 | Pipe IPC / LAN |
| ACP 协议一等一支持 | 支持接入 Zed、Cursor 等 IDE，支持会话恢复、Skills、权限桥接 | 文档 |
| Remote Control 私有部署 | Docker 自托管远程界面, 可以手机上看 CC | 文档 |
| Langfuse 监控 | 企业级 Agent 监控, 可以清晰看到每次 agent loop 细节, 可以一键转化为数据集 | 文档 |
| Web Search | 内置网页搜索工具, 支持 bing 和 brave 搜索 | 文档 |
| Poor Mode | 穷鬼模式，关闭记忆提取和键入建议,大幅度减少并发请求 | /poor 可以开关 |
| 自定义模型供应商 | OpenAI/Anthropic/Gemini/Grok 兼容 | 文档 |
| Voice Mode | Push-to-Talk 语音输入 | 文档 |
| Computer Use | 屏幕截图、键鼠控制 | 文档 |
| Chrome Use | 浏览器自动化、表单填写、数据抓取 | 自托管 原生版 |
| Sentry | 企业级错误追踪 | 文档 |
| GrowthBook | 企业级特性开关 | 文档 |
| /dream 记忆整理 | 自动整理和优化记忆文件 | 文档 |

- 🚀 想要启动项目
- 🐛 想要调试项目
- 📖 想要学习项目

⚡ 快速开始(安装版) Copy Chapter

不用克隆仓库, 从 NPM 下载后, 直接使用

bun  i -g claude-code-best
bun pm -g trust claude-code-best
ccb # 以 nodejs 打开 claude code
ccb-bun # 以 bun 形态打开
CLAUDE_BRIDGE_BASE_URL=https://remote-control.claude-code-best.win/ CLAUDE_BRIDGE_OAUTH_TOKEN=test-my-key ccb --remote-control # 我们有自部署的远程控制

⚡ 快速开始(源码版) Copy Chapter

⚙️ 环境要求 Copy Section

一定要最新版本的 bun 啊, 不然一堆奇奇怪怪的 BUG!!! bun upgrade!!!

- 📦 Bun >= 1.3.11
- ⚙️ 常规的配置 CC 的方式, 各大提供商都有自己的配置方式

📥 安装 Copy Section

bun install

▶️ 运行 Copy Section

开发模式, 看到版本号 888 说明就是对了

bun run dev
构建

bun run build

构建采用 code splitting 多文件打包（build.ts），产物输出到 dist/ 目录（入口 dist/cli.js + 约 450 个 chunk 文件）。

构建出的版本 bun 和 node 都可以启动, 你 publish 到私有源可以直接启动

如果遇到 bug 请直接提一个 issues, 我们优先解决

👤 新人配置 /login Copy Section

首次运行后，在 REPL 中输入 /login 命令进入登录配置界面，选择 Anthropic Compatible 即可对接第三方 API 兼容服务（无需 Anthropic 官方账号）。
选择 OpenAI 和 Gemini 对应的栏目都是支持相应协议的

需要填写的字段：

| 📌 字段 | 📝 说明 | 💡 示例 |
|------|------|------|
| Base URL | API 服务地址 | https://api.example.com/v1 |
| API Key | 认证密钥 | sk-xxx |
| Haiku Model | 快速模型 ID | claude-haiku-4-5-20251001 |
| Sonnet Model | 均衡模型 ID | claude-sonnet-4-6 |
| Opus Model | 高性能模型 ID | claude-opus-4-6 |

- ⌨️ Tab / Shift+Tab 切换字段，Enter 确认并跳到下一个，最后一个字段按 Enter 保存

ℹ️ 支持所有 Anthropic API 兼容服务（如 OpenRouter、AWS Bedrock 代理等），只要接口兼容 Messages API 即可。

Feature Flags Copy Chapter

所有功能开关通过 FEATURE_<FLAG_NAME>=1 环境变量启用，例如：

FEATURE_BUDDY=1 FEATURE_FORK_SUBAGENT=1 bun run dev

各 Feature 的详细说明见 docs/features/ 目录，欢迎投稿补充。

VS Code 调试 Copy Chapter

TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动调试。使用 attach 模式：

步骤 Copy Section

1. 终端启动 inspect 服务：

bun run dev:inspect

2. VS Code 附着调试器：
- 在 src/ 文件中打断点
- F5 → 选择 "Attach to Bun (TUI debug)"

Teach Me 学习项目 Copy Chapter

我们新加了一个 teach-me skills, 通过问答式引导帮你理解这个项目的任何模块。(调整 sigma skill 而来)

在 REPL 中直接输入

/teach-me Claude Code 架构
/teach-me React Ink 终端渲染 --level beginner
/teach-me Tool 系统 --resume

它能做什么 Copy Section

- 诊断水平 — 自动评估你对相关概念的掌握程度，跳过已知的、聚焦薄弱的
- 构建学习路径 — 将主题拆解为 5-15 个原子概念，按依赖排序逐步推进
- 苏格拉底式提问 — 用选项引导思考，而非直接给答案
- 错误概念追踪 — 发现并纠正深层误解
- 断点续学 — --resume 从上次进度继续

学习记录 Copy Section

学习进度保存在 .claude/skills/teach-me/ 目录下，支持跨主题学习者档案。

相关文档及网站 Copy Chapter

- 在线文档（Mintlify）: ccb.agent-aura.top — 文档源码位于 docs/ 目录，欢迎投稿 PR
- DeepWiki: <https://deepwiki.com/claude-code-best/claude-code>

Contributors Copy Chapter

<a href="https://github.com/claude-code-best/claude-code/graphs/contributors">
<img src="contributors.svg" alt="Contributors" />
</a>

Star History Copy Chapter

<a href="https://www.star-history.com/?repos=claude-code-best%2Fclaude-code&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=claude-code-best/claude-code&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=claude-code-best/claude-code&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/image?repos=claude-code-best/claude-code&type=date&legend=top-left" />
</picture>
</a>

许可证 Copy Chapter

本项目仅供学习研究用途。Claude Code 的所有权利归 Anthropic 所有。