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

bun:bundle

@commander-js/extra-typings

@anthropic-ai/sdk

Architecture

Directory Map (

src/

)

commands/

/commit

/review

/config

tools/

components/

services/

bridge/

state/

hooks/

types/

utils/

screens/

skills/

plugins/

coordinator/

tasks/

context/

memdir/

entrypoints/

voice/

vim/

schemas/

keybindings/

migrations/

outputStyles/

query/

server/

remote/

Key Files

src/main.tsx

src/QueryEngine.ts

src/Tool.ts

buildTool

src/tools.ts

src/commands.ts

src/context.ts

src/cost-tracker.ts

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}/

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

.tsx

UI.tsx

prompt.ts

Command Definition

Commands live in

src/commands/

• 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

/command-name

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

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

BashTool.tsx

commit-push-pr.ts

App.tsx

PromptInput.tsx

ToolUseContext

use

useCanUseTool

useSettings

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

services/api/

services/mcp/

services/oauth/

services/lsp/

services/analytics/

services/plugins/

services/compact/

services/policyLimits/

services/remoteManagedSettings/

services/tokenEstimation.ts

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.