2026-03-31 22:21:35 +08:00
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
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. The codebase has ~1341 tsc errors from decompilation (mostly `unknown` /`never` /`{}` types) — these do **not** block Bun runtime execution.
## Commands
```bash
# Install dependencies
bun install
2026-04-02 14:44:56 +08:00
# Dev mode (runs cli.tsx with MACRO defines injected via -d flags)
2026-03-31 22:21:35 +08:00
bun run dev
# Pipe mode
echo "say hello" | bun run src/entrypoints/cli.tsx -p
2026-04-02 14:44:56 +08:00
# Build (code splitting, outputs dist/cli.js + ~450 chunk files)
2026-03-31 22:21:35 +08:00
bun run build
2026-04-02 14:44:56 +08:00
# Test
bun test # run all tests
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/
2026-03-31 22:21:35 +08:00
```
2026-04-02 14:44:56 +08:00
详细的测试规范、覆盖状态和改进计划见 `docs/testing-spec.md` 。
2026-03-31 22:21:35 +08:00
## Architecture
### Runtime & Build
- **Runtime**: Bun (not Node.js). All imports, builds, and execution use Bun APIs.
2026-04-02 14:44:56 +08:00
- **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true` ，入口 `src/entrypoints/cli.tsx` ，输出 `dist/cli.js` + ~450 chunk files。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。
- **Dev mode**: `scripts/dev.ts` 通过 Bun `-d` flag 注入 `MACRO.*` defines， `src/entrypoints/cli.tsx` 。`scripts/defines.ts` 集中管理 define map。
2026-03-31 22:21:35 +08:00
- **Module system**: ESM (`"type": "module"` ), TSX with `react-jsx` transform.
- **Monorepo**: Bun workspaces — internal packages live in `packages/` resolved via `workspace:*` .
2026-04-02 14:44:56 +08:00
- **Lint/Format**: Biome (`biome.json` )。`bun run lint` / `bun run lint:fix` / `bun run format` 。
2026-03-31 22:21:35 +08:00
### Entry & Bootstrap
2026-04-02 21:37:30 +08:00
1. ** `src/entrypoints/cli.tsx` ** — True entrypoint. Sets up runtime globals:
- `globalThis.MACRO` — build-time macro values (VERSION, BUILD_TIME, etc.)，通过 `scripts/dev.ts` 的 `-d` flags 注入。
- `BUILD_TARGET` , `BUILD_ENV` , `INTERFACE_TYPE` globals。
- `feature()` 由 `bun:bundle` 内置模块提供，不需要在此 polyfill。
2026-03-31 22:21:35 +08:00
2. ** `src/main.tsx` ** — Commander.js CLI definition. Parses args, initializes services (auth, analytics, policy), then launches the REPL or runs in pipe mode.
3. ** `src/entrypoints/init.ts` ** — One-time initialization (telemetry, config, trust dialog).
### Core Loop
- **`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
- **`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.
- Supports multiple providers: Anthropic direct, AWS Bedrock, Google Vertex, Azure.
- Provider selection in `src/utils/model/providers.ts` .
### Tool System
- **`src/Tool.ts` ** — Tool interface definition (`Tool` type) and utilities (`findToolByName` , `toolMatchesName` ).
- **`src/tools.ts` ** — Tool registry. Assembles the tool list; some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE` .
- **`src/tools/<ToolName>/` ** — Each tool in its own directory (e.g., `BashTool` , `FileEditTool` , `GrepTool` , `AgentTool` ).
- Tools define: `name` , `description` , `inputSchema` (JSON Schema), `call()` (execution), and optionally a React component for rendering results.
### UI Layer (Ink)
- **`src/ink.ts` ** — Ink render wrapper with ThemeProvider injection.
- **`src/ink/` ** — Custom Ink framework (forked/internal): custom reconciler, hooks (`useInput` , `useTerminalSize` , `useSearchHighlight` ), virtual list rendering.
- **`src/components/` ** — React components rendered in terminal via Ink. Key ones:
- `App.tsx` — Root provider (AppState, Stats, FpsMetrics).
- `Messages.tsx` / `MessageRow.tsx` — Conversation message rendering.
- `PromptInput/` — User input handling.
- `permissions/` — Tool permission approval UI.
- Components use React Compiler runtime (`react/compiler-runtime` ) — decompiled output has `_c()` memoization calls throughout.
### State Management
- **`src/state/AppState.tsx` ** — Central app state type and context provider. Contains messages, tools, permissions, MCP connections, etc.
- **`src/state/store.ts` ** — Zustand-style store for AppState.
- **`src/bootstrap/state.ts` ** — Module-level singletons for session-global state (session ID, CWD, project root, token counts).
### Context & System Prompt
- **`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
2026-04-02 21:37:30 +08:00
Feature flags control which functionality is enabled at runtime. The system works as follows:
- **在代码中使用**: 统一通过 `import { feature } from 'bun:bundle'` 导入，调用 `feature('FLAG_NAME')` 返回 `boolean` 。**不要**在 `cli.tsx` 或其他文件里自己定义 `feature` 函数或覆盖这个 import。
- **启用方式**: 通过环境变量 `FEATURE_<FLAG_NAME>=1` 。例如 `FEATURE_BUDDY=1 bun run dev` 启用 BUDDY 功能。
- **Dev 模式**: `scripts/dev.ts` 自动扫描所有 `FEATURE_*` 环境变量，转换为 Bun 的 `--feature` 参数传递给运行时。
- **Build 模式**: `build.ts` 同样读取 `FEATURE_*` 环境变量，传入 `Bun.build({ features })` 数组。
- **默认行为**: 不设置任何 `FEATURE_*` 环境变量时，所有 `feature()` 调用返回 `false` ，即所有 feature-gated 代码不执行。
- **常见 flag 名称**: `BUDDY` 、`FORK_SUBAGENT` 、`PROACTIVE` 、`KAIROS` 、`VOICE_MODE` 、`DAEMON` 等（见 `src/commands.ts` 中的使用）。
- **类型声明**: `src/types/internal-modules.d.ts` 中声明了 `bun:bundle` 模块的 `feature` 函数签名。
**新增功能的正确做法**: 如果要让某个 feature-gated 模块（如 buddy） ， `import { feature } from 'bun:bundle'` + `feature('FLAG_NAME')` 的标准模式，在运行时通过环境变量或配置控制，而不是绕过 feature flag 直接 import。
2026-03-31 22:21:35 +08:00
### Stubbed/Deleted Modules
| Module | Status |
|--------|--------|
| Computer Use (`@ant/*` ) | Stub packages in `packages/@ant/` |
| `*-napi` packages (audio, image, url, modifiers) | Stubs in `packages/` (except `color-diff-napi` which is fully implemented) |
| Analytics / GrowthBook / Sentry | Empty implementations |
| Magic Docs / Voice Mode / LSP Server | Removed |
| Plugins / Marketplace | Removed |
| MCP OAuth | Simplified |
### Key Type Files
- **`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.
2026-04-02 14:44:56 +08:00
## Testing
- **框架**: `bun:test` （内置断言 + mock）
- **单元测试**: 就近放置于 `src/**/__tests__/` ，文件名 `<module>.test.ts`
- **集成测试**: `tests/integration/` ，共享 mock/fixture 在 `tests/mocks/`
- **命名**: `describe("functionName")` + `test("behavior description")` ，英文
- **Mock 模式**: 对重依赖模块使用 `mock.module()` + `await import()` 解锁（必须内联在测试文件中，不能从共享 helper 导入）
- **当前状态**: 1286 tests / 67 files / 0 fail（ `docs/testing-spec.md` 的覆盖状态表和评分）
2026-03-31 22:21:35 +08:00
## Working with This Codebase
- **Don't try to fix all tsc errors** — they're from decompilation and don't affect runtime.
2026-04-02 21:37:30 +08:00
- **Feature flags** — 默认全部关闭（`feature()` 返回 `false` ）。启用方式见上方 Feature Flag System 章节。不要在 `cli.tsx` 中重定义 `feature` 函数。
2026-03-31 22:21:35 +08:00
- **React Compiler output** — Components have decompiled memoization boilerplate (`const $ = _c(N)` ). This is normal.
2026-04-02 21:37:30 +08:00
- **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。
2026-03-31 22:21:35 +08:00
- **`src/` path alias** — tsconfig maps `src/*` to `./src/*` . Imports like `import { ... } from 'src/utils/...'` are valid.
2026-04-02 14:44:56 +08:00
- **MACRO defines** — 集中管理在 `scripts/defines.ts` 。Dev mode 通过 `bun -d` 注入， `Bun.build({ define })` 注入。修改版本号等常量只改这个文件。
- **构建产物兼容 Node.js** — `build.ts` 会自动后处理 `import.meta.require` ，产物可直接用 `node dist/cli.js` 运行。
