---
name: Claude Code Conventions
slug: claude-code-conventions
category: AI Engineering
description: Claude Code Conventions documents the architecture, directory map, and coding patterns for the Claude Code CLI codebase. Use it when building tools, commands, or components for Claude Code.
github: "https://github.com/codeaashu/claude-code/tree/main/Skill.md"
language: TypeScript
stars: 3236
forks: 3646
install: "npx degit https://github.com/codeaashu/claude-code/tree/main ~/.claude/skills/claude-code"
installs_to: ~/.claude/skills/claude-code
source_path: Skill.md
collection_size: 1
category_size: 2451
added: 2026-08-17T07:08:48.657Z
last_synced: 2026-08-17T07:08:48.657Z
canonical_url: "https://dirskills.com/skills/claude-code-conventions"
---

# Claude Code Conventions

Claude Code Conventions documents the architecture, directory map, and coding patterns for the Claude Code CLI codebase. Use it when building tools, commands, or components for Claude Code.

**Install:**

```bash
npx degit https://github.com/codeaashu/claude-code/tree/main ~/.claude/skills/claude-code
```

## README

# 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

1. `src/main.tsx` — Commander CLI parser, startup profiling
2. `src/entrypoints/init.ts` — Config, telemetry, OAuth, MDM
3. `src/entrypoints/cli.tsx` — CLI session orchestration
4. `src/entrypoints/mcp.ts` — MCP server mode
5. `src/entrypoints/sdk/` — Agent SDK (programmatic API)
6. `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`:

```typescript
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

```typescript
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:

```typescript
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

1. Read relevant source files before making changes — understand existing patterns first.
2. Follow the tool/command/component patterns above when adding new ones.
3. Keep edits minimal and focused — avoid unnecessary refactoring.
4. Use Zod for all input validation at system boundaries.
5. Gate experimental features behind `bun:bundle` feature flags or env checks.
6. Respect the permission system — tools that modify state must implement `checkPermissions()`.
7. Use lazy imports when adding dependencies that could create circular references.
8. Update this file as project conventions evolve.