Claude Code — Repository Skill
Project Overview
Claude Code is Anthropic's CLI tool for interacting with Claude from the terminal. It supports file editing, shell commands, git workflows, code review, multi-agent coordination, IDE integration (VS Code, JetBrains), and Model Context Protocol (MCP).
Codebase: ~1,900 files, 512,000+ lines of TypeScript under src/.
Tech Stack
| Component |
Technology |
| Language |
TypeScript (strict mode, ES modules) |
| Runtime |
Bun (JSX support, bun:bundle feature flags) |
| Terminal UI |
React + Ink (React for CLI) |
| CLI Parser |
Commander.js (@commander-js/extra-typings) |
| API Client |
@anthropic-ai/sdk |
| Validation |
Zod v4 |
| Linter/Formatter |
Biome |
| Analytics |
GrowthBook (feature flags & A/B testing) |
| Protocol |
Model Context Protocol (MCP) |
Architecture
Directory Map (src/)
| Directory |
Purpose |
commands/ |
~50 slash commands (/commit, /review, /config, etc.) |
tools/ |
~40 agent tools (Bash, FileRead, FileWrite, Glob, Grep, etc.) |
components/ |
~140 Ink/React UI components for terminal rendering |
services/ |
External integrations (API, OAuth, MCP, LSP, analytics, plugins) |
bridge/ |
Bidirectional IDE communication layer |
state/ |
React context + custom store (AppState) |
hooks/ |
React hooks (permissions, keybindings, commands, settings) |
types/ |
TypeScript type definitions |
utils/ |
Utilities (shell, file ops, permissions, config, git) |
screens/ |
Full-screen UIs (Doctor, REPL, Resume, Compact) |
skills/ |
Bundled skills + skill loader system |
plugins/ |
Plugin system (marketplace + bundled plugins) |
coordinator/ |
Multi-agent coordination & supervisor logic |
tasks/ |
Task management (shell tasks, agent tasks, teammates) |
context/ |
React context providers (notifications, stats, FPS) |
memdir/ |
Persistent memory system (CLAUDE.md, user/project memory) |
entrypoints/ |
Initialization logic, Agent SDK, MCP entry |
voice/ |
Voice input/output (STT, keyterms) |
vim/ |
Vim mode keybinding support |
schemas/ |
Zod configuration schemas |
keybindings/ |
Keybinding configuration & resolver |
migrations/ |
Config migrations between versions |
outputStyles/ |
Output formatting & theming |
query/ |
Query pipeline & processing |
server/ |
Server/daemon mode |
remote/ |
Remote session handling |
Key Files
| File |
Role |
src/main.tsx |
CLI entry point (Commander parser, startup profiling) |
src/QueryEngine.ts |
Core LLM API caller (streaming, tool-call loops) |
src/Tool.ts |
Tool type definitions & buildTool factory |
src/tools.ts |
Tool registry & presets |
src/commands.ts |
Command registry |
src/context.ts |
System/user context collection (git status, memory) |
src/cost-tracker.ts |
Token cost tracking |
Entry Points & Initialization Sequence
src/main.tsx — Commander CLI parser, startup profilingsrc/entrypoints/init.ts — Config, telemetry, OAuth, MDMsrc/entrypoints/cli.tsx — CLI session orchestrationsrc/entrypoints/mcp.ts — MCP server modesrc/entrypoints/sdk/ — Agent SDK (programmatic API)src/replLauncher.tsx — REPL session launcher
Startup performs parallel initialization: MDM policy reads, Keychain prefetch, feature flag checks, then core init.
Patterns & Conventions
Tool Definition
Each tool lives in src/tools/{ToolName}/ and uses buildTool:
export const MyTool = buildTool({
name: 'MyTool',
aliases: ['my_tool'],
description: 'What this tool does',
inputSchema: z.object({
param: z.string(),
}),
async call(args, context, canUseTool, parentMessage, onProgress) {
// Execute and return { data: result, newMessages?: [...] }
},
async checkPermissions(input, context) { /* Permission checks */ },
isConcurrencySafe(input) { /* Can run in parallel? */ },
isReadOnly(input) { /* Non-destructive? */ },
prompt(options) { /* System prompt injection */ },
renderToolUseMessage(input, options) { /* UI for invocation */ },
renderToolResultMessage(content, progressMessages, options) { /* UI for result */ },
})
Directory structure per tool: {ToolName}.ts or .tsx (main), UI.tsx (rendering), prompt.ts (system prompt), plus utility files.
Command Definition
Commands live in src/commands/ and follow three types:
- PromptCommand — Sends a formatted prompt with injected tools (most commands)
- LocalCommand — Runs in-process, returns text
- LocalJSXCommand — Runs in-process, returns React JSX
const command = {
type: 'prompt',
name: 'my-command',
description: 'What this command does',
progressMessage: 'working...',
allowedTools: ['Bash(git *)', 'FileRead(*)'],
source: 'builtin',
async getPromptForCommand(args, context) {
return [{ type: 'text', text: '...' }]
},
} satisfies Command
Commands are registered in src/commands.ts and invoked via /command-name in the REPL.
Component Structure
- Functional React components with Ink primitives (
Box, Text, useInput())
- Styled with Chalk for terminal colors
- React Compiler for optimized re-renders
- Design system primitives in
src/components/design-system/
State Management
AppState via React context + custom store (src/state/AppStateStore.ts)- Mutable state object passed to tool contexts
- Selector functions for derived state
- Change observers in
src/state/onChangeAppState.ts
Permission System
- Modes:
default (prompt per operation), plan (show plan, ask once), bypassPermissions (auto-approve), auto (ML classifier)
- Rules: Wildcard patterns —
Bash(git *), FileEdit(/src/*)
- Tools implement
checkPermissions() returning { granted: boolean, reason?, prompt? }
Feature Flags & Build
Bun's bun:bundle feature flags enable dead-code elimination at build time:
import { feature } from 'bun:bundle'
if (feature('PROACTIVE')) { /* proactive agent tools */ }
Notable flags: PROACTIVE, KAIROS, BRIDGE_MODE, VOICE_MODE, COORDINATOR_MODE, DAEMON, WORKFLOW_SCRIPTS.
Some features are also gated via process.env.USER_TYPE === 'ant'.
Naming Conventions
| Element |
Convention |
Example |
| Files |
PascalCase (exports) or kebab-case (commands) |
BashTool.tsx, commit-push-pr.ts |
| Components |
PascalCase |
App.tsx, PromptInput.tsx |
| Types |
PascalCase, suffix with Props/State/Context |
ToolUseContext |
| Hooks |
use prefix |
useCanUseTool, useSettings |
| Constants |
SCREAMING_SNAKE_CASE |
MAX_TOKENS, DEFAULT_TIMEOUT_MS |
Import Practices
- ES modules with
.js extensions (Bun convention)
- Lazy imports for circular dependency breaking:
const getModule = () => require('./heavy.js')
- Conditional imports via feature flags or
process.env
biome-ignore markers for manual import ordering where needed
Services
| Service |
Path |
Purpose |
| API |
services/api/ |
Anthropic SDK client, file uploads |
| MCP |
services/mcp/ |
MCP client, tool/resource discovery |
| OAuth |
services/oauth/ |
OAuth 2.0 auth flow |
| LSP |
services/lsp/ |
Language Server Protocol manager |
| Analytics |
services/analytics/ |
GrowthBook, telemetry, events |
| Plugins |
services/plugins/ |
Plugin loader, marketplace |
| Compact |
services/compact/ |
Context compression |
| Policy Limits |
services/policyLimits/ |
Org rate limits, quota checking |
| Remote Settings |
services/remoteManagedSettings/ |
Managed settings sync (Enterprise) |
| Token Estimation |
services/tokenEstimation.ts |
Token count estimation |
Configuration
Settings locations:
- Global:
~/.claude/config.json, ~/.claude/settings.json
- Project:
.claude/config.json, .claude/settings.json
- System: macOS Keychain + MDM, Windows Registry + MDM
- Managed: Remote sync for Enterprise users
Guidelines
- Read relevant source files before making changes — understand existing patterns first.
- Follow the tool/command/component patterns above when adding new ones.
- Keep edits minimal and focused — avoid unnecessary refactoring.
- Use Zod for all input validation at system boundaries.
- Gate experimental features behind
bun:bundle feature flags or env checks.
- Respect the permission system — tools that modify state must implement
checkPermissions().
- Use lazy imports when adding dependencies that could create circular references.
- Update this file as project conventions evolve.
1---2name: claude-code-skill3description: Development conventions and architecture guide for the Claude Code CLI repository.4---5
6# Claude Code — Repository Skill
7
8## Project Overview
9
10Claude Code is Anthropic's CLI tool for interacting with Claude from the terminal. It supports file editing, shell commands, git workflows, code review, multi-agent coordination, IDE integration (VS Code, JetBrains), and Model Context Protocol (MCP).
11
12**Codebase:** ~1,900 files, 512,000+ lines of TypeScript under `src/`.
13
14## Tech Stack
15
16| Component | Technology |
17|------------------|------------------------------------------------|
18| Language | TypeScript (strict mode, ES modules) |
19| Runtime | Bun (JSX support, `bun:bundle` feature flags) |
20| Terminal UI | React + Ink (React for CLI) |
21| CLI Parser | Commander.js (`@commander-js/extra-typings`) |
22| API Client | `@anthropic-ai/sdk` |
23| Validation | Zod v4 |
24| Linter/Formatter | Biome |
25| Analytics | GrowthBook (feature flags & A/B testing) |
26| Protocol | Model Context Protocol (MCP) |
27
28## Architecture
29
30### Directory Map (`src/`)
31
32| Directory | Purpose |
33|------------------|-----------------------------------------------------------------|
34| `commands/` | ~50 slash commands (`/commit`, `/review`, `/config`, etc.) |
35| `tools/` | ~40 agent tools (Bash, FileRead, FileWrite, Glob, Grep, etc.) |
36| `components/` | ~140 Ink/React UI components for terminal rendering |
37| `services/` | External integrations (API, OAuth, MCP, LSP, analytics, plugins)|
38| `bridge/` | Bidirectional IDE communication layer |
39| `state/` | React context + custom store (AppState) |
40| `hooks/` | React hooks (permissions, keybindings, commands, settings) |
41| `types/` | TypeScript type definitions |
42| `utils/` | Utilities (shell, file ops, permissions, config, git) |
43| `screens/` | Full-screen UIs (Doctor, REPL, Resume, Compact) |
44| `skills/` | Bundled skills + skill loader system |
45| `plugins/` | Plugin system (marketplace + bundled plugins) |
46| `coordinator/` | Multi-agent coordination & supervisor logic |
47| `tasks/` | Task management (shell tasks, agent tasks, teammates) |
48| `context/` | React context providers (notifications, stats, FPS) |
49| `memdir/` | Persistent memory system (CLAUDE.md, user/project memory) |
50| `entrypoints/` | Initialization logic, Agent SDK, MCP entry |
51| `voice/` | Voice input/output (STT, keyterms) |
52| `vim/` | Vim mode keybinding support |
53| `schemas/` | Zod configuration schemas |
54| `keybindings/` | Keybinding configuration & resolver |
55| `migrations/` | Config migrations between versions |
56| `outputStyles/` | Output formatting & theming |
57| `query/` | Query pipeline & processing |
58| `server/` | Server/daemon mode |
59| `remote/` | Remote session handling |
60
61### Key Files
62
63| File | Role |
64|---------------------|-----------------------------------------------------|
65| `src/main.tsx` | CLI entry point (Commander parser, startup profiling)|
66| `src/QueryEngine.ts`| Core LLM API caller (streaming, tool-call loops) |
67| `src/Tool.ts` | Tool type definitions & `buildTool` factory |
68| `src/tools.ts` | Tool registry & presets |
69| `src/commands.ts` | Command registry |
70| `src/context.ts` | System/user context collection (git status, memory) |
71| `src/cost-tracker.ts`| Token cost tracking |
72
73### Entry Points & Initialization Sequence
74
751. `src/main.tsx` — Commander CLI parser, startup profiling
762. `src/entrypoints/init.ts` — Config, telemetry, OAuth, MDM
773. `src/entrypoints/cli.tsx` — CLI session orchestration
784. `src/entrypoints/mcp.ts` — MCP server mode
795. `src/entrypoints/sdk/` — Agent SDK (programmatic API)
806. `src/replLauncher.tsx` — REPL session launcher
81
82Startup performs parallel initialization: MDM policy reads, Keychain prefetch, feature flag checks, then core init.
83
84## Patterns & Conventions
85
86### Tool Definition
87
88Each tool lives in `src/tools/{ToolName}/` and uses `buildTool`:
89
90```typescript
91export const MyTool = buildTool({
92 name: 'MyTool',
93 aliases: ['my_tool'],
94 description: 'What this tool does',
95 inputSchema: z.object({
96 param: z.string(),
97 }),
98 async call(args, context, canUseTool, parentMessage, onProgress) {
99 // Execute and return { data: result, newMessages?: [...] }
100 },
101 async checkPermissions(input, context) { /* Permission checks */ },
102 isConcurrencySafe(input) { /* Can run in parallel? */ },
103 isReadOnly(input) { /* Non-destructive? */ },
104 prompt(options) { /* System prompt injection */ },
105 renderToolUseMessage(input, options) { /* UI for invocation */ },
106 renderToolResultMessage(content, progressMessages, options) { /* UI for result */ },
107})
108```
109
110**Directory structure per tool:** `{ToolName}.ts` or `.tsx` (main), `UI.tsx` (rendering), `prompt.ts` (system prompt), plus utility files.
111
112### Command Definition
113
114Commands live in `src/commands/` and follow three types:
115
116- **PromptCommand** — Sends a formatted prompt with injected tools (most commands)
117- **LocalCommand** — Runs in-process, returns text
118- **LocalJSXCommand** — Runs in-process, returns React JSX
119
120```typescript
121const command = {
122 type: 'prompt',
123 name: 'my-command',
124 description: 'What this command does',
125 progressMessage: 'working...',
126 allowedTools: ['Bash(git *)', 'FileRead(*)'],
127 source: 'builtin',
128 async getPromptForCommand(args, context) {
129 return [{ type: 'text', text: '...' }]
130 },
131} satisfies Command
132```
133
134Commands are registered in `src/commands.ts` and invoked via `/command-name` in the REPL.
135
136### Component Structure
137
138- Functional React components with Ink primitives (`Box`, `Text`, `useInput()`)
139- Styled with Chalk for terminal colors
140- React Compiler for optimized re-renders
141- Design system primitives in `src/components/design-system/`
142
143### State Management
144
145- `AppState` via React context + custom store (`src/state/AppStateStore.ts`)
146- Mutable state object passed to tool contexts
147- Selector functions for derived state
148- Change observers in `src/state/onChangeAppState.ts`
149
150### Permission System
151
152- **Modes:** `default` (prompt per operation), `plan` (show plan, ask once), `bypassPermissions` (auto-approve), `auto` (ML classifier)
153- **Rules:** Wildcard patterns — `Bash(git *)`, `FileEdit(/src/*)`
154- Tools implement `checkPermissions()` returning `{ granted: boolean, reason?, prompt? }`
155
156### Feature Flags & Build
157
158Bun's `bun:bundle` feature flags enable dead-code elimination at build time:
159
160```typescript
161import { feature } from 'bun:bundle'
162if (feature('PROACTIVE')) { /* proactive agent tools */ }
163```
164
165Notable flags: `PROACTIVE`, `KAIROS`, `BRIDGE_MODE`, `VOICE_MODE`, `COORDINATOR_MODE`, `DAEMON`, `WORKFLOW_SCRIPTS`.
166
167Some features are also gated via `process.env.USER_TYPE === 'ant'`.
168
169## Naming Conventions
170
171| Element | Convention | Example |
172|-------------|---------------------|----------------------------------|
173| Files | PascalCase (exports) or kebab-case (commands) | `BashTool.tsx`, `commit-push-pr.ts` |
174| Components | PascalCase | `App.tsx`, `PromptInput.tsx` |
175| Types | PascalCase, suffix with Props/State/Context | `ToolUseContext` |
176| Hooks | `use` prefix | `useCanUseTool`, `useSettings` |
177| Constants | SCREAMING_SNAKE_CASE | `MAX_TOKENS`, `DEFAULT_TIMEOUT_MS`|
178
179## Import Practices
180
181- ES modules with `.js` extensions (Bun convention)
182- Lazy imports for circular dependency breaking: `const getModule = () => require('./heavy.js')`
183- Conditional imports via feature flags or `process.env`
184- `biome-ignore` markers for manual import ordering where needed
185
186## Services
187
188| Service | Path | Purpose |
189|--------------------|-------------------------------|-----------------------------------|
190| API | `services/api/` | Anthropic SDK client, file uploads|
191| MCP | `services/mcp/` | MCP client, tool/resource discovery|
192| OAuth | `services/oauth/` | OAuth 2.0 auth flow |
193| LSP | `services/lsp/` | Language Server Protocol manager |
194| Analytics | `services/analytics/` | GrowthBook, telemetry, events |
195| Plugins | `services/plugins/` | Plugin loader, marketplace |
196| Compact | `services/compact/` | Context compression |
197| Policy Limits | `services/policyLimits/` | Org rate limits, quota checking |
198| Remote Settings | `services/remoteManagedSettings/` | Managed settings sync (Enterprise) |
199| Token Estimation | `services/tokenEstimation.ts` | Token count estimation |
200
201## Configuration
202
203**Settings locations:**
204- **Global:** `~/.claude/config.json`, `~/.claude/settings.json`
205- **Project:** `.claude/config.json`, `.claude/settings.json`
206- **System:** macOS Keychain + MDM, Windows Registry + MDM
207- **Managed:** Remote sync for Enterprise users
208
209## Guidelines
210
2111. Read relevant source files before making changes — understand existing patterns first.
2122. Follow the tool/command/component patterns above when adding new ones.
2133. Keep edits minimal and focused — avoid unnecessary refactoring.
2144. Use Zod for all input validation at system boundaries.
2155. Gate experimental features behind `bun:bundle` feature flags or env checks.
2166. Respect the permission system — tools that modify state must implement `checkPermissions()`.
2177. Use lazy imports when adding dependencies that could create circular references.
2188. Update this file as project conventions evolve.
219
220
majiayu000