baobeld/claude-code
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

hello world

Browse source
This commit is contained in:
kuberwastaken 2026-04-01 01:20:27 +05:30
commit c99507ca1e
84 changed files with 54252 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

334
spec/00_overview.md Normal file
View file

@ -0,0 +1,334 @@
# Claude Code — Master Architecture Overview
> **Repository:** `X:\Bigger-Projects\Claude-Code`
> **Primary Language:** TypeScript/TSX (~1,902 files, ~800K+ LOC)
> **Secondary Language:** Rust (~47 files, in-progress port)
> **Bundler:** Bun
> **UI Framework:** Custom Ink (React reconciler for terminal)
> **Runtime Target:** Node.js / Bun CLI
---
## 1. What Is Claude Code?
Claude Code is an AI-powered CLI tool and coding assistant. It is a full-featured interactive terminal application that:
- Embeds a Claude AI model as an agentic coding assistant
- Runs in the terminal using a custom React-based TUI (Terminal User Interface)
- Executes tools (file read/write, bash, grep, web search, etc.) with user permission
- Supports multi-agent task delegation, background agents, and swarm mode
- Integrates with IDEs (VS Code, JetBrains) via direct-connect bridge
- Supports remote sessions via WebSocket/SSE transports
- Has a plugin/skills marketplace
- Includes voice input (speech-to-text)
- Features a companion "buddy" system (Tamagotchi-style)
- Syncs sessions to the cloud via the bridge protocol
---
## 2. Repository Structure
```
Claude-Code/
├── src/ # Main TypeScript/TSX source (34 MB, ~1,902 files)
│ ├── main.tsx # PRIMARY ENTRY POINT (4,683 lines)
│ ├── replLauncher.tsx # REPL mode launcher
│ ├── query.ts # Main query/turn execution engine (69KB)
│ ├── QueryEngine.ts # Query engine class (46KB)
│ ├── Tool.ts # Tool base framework (30KB)
│ ├── Task.ts # Task definitions
│ ├── commands.ts # Command registry (25KB)
│ ├── context.ts # Context management
│ ├── cost-tracker.ts # Cost tracking (11KB)
│ ├── costHook.ts # Cost hooks
│ ├── history.ts # Session history (14KB)
│ ├── dialogLaunchers.tsx # Dialog launchers (23KB)
│ ├── interactiveHelpers.tsx # Interactive UI helpers (57KB)
│ ├── projectOnboardingState.ts # Project onboarding state
│ ├── setup.ts # Initialization (21KB)
│ ├── tasks.ts # Task management
│ ├── tools.ts # Tools registry (17KB)
│ ├── ink.ts # Ink export shim
│ │
│ ├── assistant/ # Assistant session history
│ ├── bootstrap/ # Bootstrap/state
│ ├── bridge/ # Bridge protocol (31 files)
│ ├── buddy/ # Companion pet system (6 files)
│ ├── cli/ # CLI framework & transports (19 files)
│ ├── commands/ # 87 slash commands (207 files)
│ ├── components/ # React/Ink UI components (389 files, 32 subdirs)
│ ├── constants/ # Constants & config values (21 files)
│ ├── context/ # React context providers (9 files)
│ ├── coordinator/ # Coordinator mode logic
│ ├── entrypoints/ # Multiple entry points (8 files)
│ ├── hooks/ # React hooks (104 files)
│ ├── ink/ # Custom Ink terminal framework (96 files)
│ ├── keybindings/ # Keyboard shortcut system (14 files)
│ ├── memdir/ # Memory directory system (8 files)
│ ├── migrations/ # Settings migrations (11 files)
│ ├── moreright/ # useMoreRight hook
│ ├── native-ts/ # Native TypeScript bindings (4 files)
│ ├── outputStyles/ # Output style loader
│ ├── plugins/ # Plugin system (2 files)
│ ├── query/ # Query helpers (4 files)
│ ├── remote/ # Remote session management (4 files)
│ ├── schemas/ # Zod/JSON schemas
│ ├── screens/ # Top-level screen layouts (3 files)
│ ├── server/ # Direct-connect server (3 files)
│ ├── services/ # Business logic services (130 files)
│ ├── skills/ # Claude skills/slash commands (20 files)
│ ├── tools/ # Tool implementations (40+ tools, 184 files)
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions (~564 files)
│ └── voice/ # Voice integration
│
├── claude-code-rust/ # Rust port (in-progress, 47 files)
│ ├── Cargo.toml # Workspace manifest
│ ├── tools/ # 27 files — tool implementations
│ ├── query/ # 5 files — query system
│ ├── cli/ # 3 files — CLI framework
│ ├── api/ # 2 files — API bindings
│ ├── bridge/ # 2 files — bridge protocol
│ ├── commands/ # 2 files — command system
│ ├── core/ # 2 files — core utilities
│ ├── mcp/ # 2 files — MCP integration
│ └── tui/ # 2 files — terminal UI
│
├── public/ # Static assets
├── README.md # Main documentation (27KB)
└── .git/ # Git metadata
```
---
## 3. High-Level Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ USER INTERFACE │
│ Terminal (Ink TUI) ←→ React Components ←→ Hooks ←→ Context │
└────────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────────┐
│ MAIN APPLICATION │
│ main.tsx → REPL.tsx → PromptInput → MessageList │
│ Commands (87) ←→ Command Registry ←→ Plugin System │
└────────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────────┐
│ QUERY ENGINE │
│ query.ts → QueryEngine.ts → Tool execution → Response handling │
│ Token budget → Stop hooks → Compact → History │
└────────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────────┐
│ TOOL SYSTEM (40+ tools) │
│ BashTool, FileReadTool, FileEditTool, FileWriteTool │
│ GlobTool, GrepTool, WebFetchTool, WebSearchTool │
│ AgentTool, TaskCreateTool, MCPTool, SkillTool, ... │
└────────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────────┐
│ SERVICES LAYER │
│ API Client (claude.ts) → Analytics → SessionMemory │
│ AutoDream → Compact → RateLimit → MCP servers │
└────────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────────┐
│ TRANSPORT LAYER │
│ CLI (local) / Bridge (remote) / IDE direct-connect │
│ SSETransport | WebSocketTransport | HybridTransport │
└─────────────────────────────────────────────────────────────────┘
```
---
## 4. Core Subsystems
### 4.1 Query / Turn Execution (`query.ts`, `QueryEngine.ts`)
The core loop that:
1. Takes user input
2. Builds the API request (system prompt + history + tools)
3. Streams the response from Claude API
4. Handles tool use (executes tools, feeds results back)
5. Manages token budget and context compaction
6. Tracks cost
### 4.2 Tool Framework (`Tool.ts`, `tools/`)
- Base `Tool` abstract class/interface
- Input schema validation (Zod)
- Permission system (each tool declares required permissions)
- 40+ tool implementations
- Sandboxing for dangerous tools
### 4.3 Terminal UI (`ink/`, `components/`)
- Custom React reconciler that renders to terminal
- Layout engine based on Yoga (flexbox for terminal)
- Event system (keyboard, mouse, focus)
- ANSI/CSI/escape sequence processing
- Components: Messages, PromptInput, Spinner, Dialogs, etc.
### 4.4 Commands System (`commands/`, `commands.ts`)
- 87 slash commands (e.g., `/compact`, `/diff`, `/plan`, `/mcp`)
- Plugin-contributed commands
- Command registry with fuzzy matching
- Keybinding integration
### 4.5 Bridge Protocol (`bridge/`)
- Enables remote/cloud-synced sessions
- JWT-authenticated WebSocket/SSE connection to cloud backend servers
- REPL bridge for IDE integration
- Message polling, flush gates, session runners
### 4.6 Multi-Agent System (`tools/AgentTool.ts`, `components/agents/`)
- Spawn sub-agents as isolated Claude instances
- Background task execution
- Coordinator mode (orchestrate multiple agents)
- Swarm mode (parallel worker agents)
- Team system for collaborative agents
### 4.7 Memory System (`memdir/`, `services/SessionMemory/`, `services/autoDream/`)
- Short-term: session history
- Long-term: memdir (markdown files in `~/.claude/memory/`)
- Auto-consolidation: "dream" service consolidates memories during idle
- Memory scanning/relevance scoring for context injection
### 4.8 MCP Integration (`tools/MCPTool.ts`, `components/mcp/`, `entrypoints/mcp.ts`)
- Model Context Protocol server support
- Dynamic tool registration from MCP servers
- Resource management
- Elicitation dialog support
### 4.9 Plugin/Skills System (`plugins/`, `skills/`, `commands/plugin/`)
- Built-in plugins
- Marketplace for community plugins
- Skills: user-invocable slash command macros
- Plugin trust model with approval flow
### 4.10 IDE Integration (`bridge/`, `hooks/useIDEIntegration.tsx`)
- VS Code / JetBrains extensions connect via direct-connect
- Live diff viewing in IDE
- File selection sync (IDE → Claude)
- Status indicator in IDE
---
## 5. Data Flow: A User Turn
```
1. User types in PromptInput
2. Input submitted → useCommandQueue processes
3. If slash command: dispatched to command handler
4. If regular prompt: sent to query.ts runQuery()
5. QueryEngine builds API request:
- System prompt (from constants/prompts.ts + CLAUDE.md)
- Message history (from history.ts)
- Available tools (filtered by permission)
- Token budget constraints
6. Stream response from the Claude API (services/api/claude.ts)
7. For each content block:
- text → render AssistantTextMessage
- thinking → render AssistantThinkingMessage
- tool_use → execute tool, show permission dialog if needed
8. Tool results fed back into next API request
9. Loop until stop condition (no more tool use, stop hook, budget exceeded)
10. Final response rendered, history updated, cost tracked
```
---
## 6. Key Files by Importance
| Rank | File | Size | Role |
|------|------|------|------|
| 1 | `src/main.tsx` | 4,683 lines | Primary entry point, app initialization |
| 2 | `src/query.ts` | 69KB | Main query execution loop |
| 3 | `src/QueryEngine.ts` | 46KB | Query engine class |
| 4 | `src/interactiveHelpers.tsx` | 57KB | Interactive UI helpers |
| 5 | `src/Tool.ts` | 30KB | Tool base framework |
| 6 | `src/commands.ts` | 25KB | Command registry |
| 7 | `src/dialogLaunchers.tsx` | 23KB | Dialog launch system |
| 8 | `src/setup.ts` | 21KB | Initialization |
| 9 | `src/tools.ts` | 17KB | Tools registry |
| 10 | `src/history.ts` | 14KB | Session history |
---
## 7. Permission Model
Claude Code uses a layered permission system:
1. **Automatic** — Read-only operations, info queries
2. **Ask Once** — Prompt user, remember for session
3. **Ask Always** — Prompt user every time
4. **Deny** — Block completely
Permission rules are stored in settings (global `~/.claude/settings.json`, project `.claude/settings.json`) and can be configured with patterns.
Permission categories:
- `Bash` — Shell command execution
- `FileRead` — Reading files/directories
- `FileEdit` — Editing existing files
- `FileWrite` — Creating new files
- `WebFetch` — HTTP requests
- `MCP` — MCP tool calls
- `Sandbox` — Sandboxed execution
---
## 8. Settings System
Layered settings (in priority order):
1. **Managed** — Enterprise/managed settings (read-only)
2. **Local project** — `.claude/settings.local.json` (gitignored)
3. **Project** — `.claude/settings.json` (shared)
4. **Global** — `~/.claude/settings.json`
Settings include: model selection, permission rules, API key, theme, keybindings, MCP server configurations, beta features.
---
## 9. Model Support
Based on migration files, the model evolution:
- `claude-3-sonnet` → `claude-sonnet-1m` → `claude-sonnet-4-5` → `claude-sonnet-4-6`
- `claude-3-opus` → `claude-opus-1m` → `claude-opus` → (various)
- `claude-3-5-haiku` → (current)
- `claude-haiku-4-5` (current haiku)
Current defaults (as of source): `claude-sonnet-4-6` and `claude-opus-4-6`
---
## 10. Analytics & Telemetry
- **First-party logging** — Session events to the backend (`services/analytics/`)
- **Datadog** — Performance metrics
- **Growthbook** — Feature flags / A/B testing
- **Opt-out** — `services/api/metricsOptOut.ts` handles user opt-out
---
## 11. Spec Document Index
| File | Contents |
|------|----------|
| `00_overview.md` | This file — master architecture overview |
| `01_core_entry_query.md` | Entry points, query system, history, cost tracking |
| `02_commands.md` | All 87 slash commands |
| `03_tools.md` | All 40+ tool implementations |
| `04_components_core_messages.md` | Top-level components and message components |
| `05_components_agents_permissions_design.md` | Agents, permissions, design system, feature modules |
| `06_services_context_state.md` | Services, context providers, state, screens, server |
| `07_hooks.md` | All React hooks |
| `08_ink_terminal.md` | Ink terminal rendering framework |
| `09_bridge_cli_remote.md` | Bridge protocol, CLI framework, remote sessions |
| `10_utils.md` | All utility functions (~564 files) |
| `11_special_systems.md` | Buddy, memory, keybindings, skills, voice, plugins |
| `12_constants_types.md` | All constants, types, and configuration |
| `13_rust_codebase.md` | Rust port/rewrite |
| `INDEX.md` | Quick-reference index |
---
*Generated from source analysis of the Claude Code codebase. ~1,902 TypeScript/TSX files, ~800K+ lines of code.*

1925
spec/01_core_entry_query.md Normal file
View file

File diff suppressed because it is too large Load diff

2065
spec/02_commands.md Normal file
View file

File diff suppressed because it is too large Load diff

2171
spec/03_tools.md Normal file
View file

File diff suppressed because it is too large Load diff

2586
spec/04_components_core_messages.md Normal file
View file

File diff suppressed because it is too large Load diff

1952
spec/05_components_agents_permissions_design.md Normal file
View file

File diff suppressed because it is too large Load diff

2631
spec/06_services_context_state.md Normal file
View file

File diff suppressed because it is too large Load diff

2136
spec/07_hooks.md Normal file
View file

File diff suppressed because it is too large Load diff

1608
spec/08_ink_terminal.md Normal file
View file

File diff suppressed because it is too large Load diff

2233
spec/09_bridge_cli_remote.md Normal file
View file

File diff suppressed because it is too large Load diff

2182
spec/10_utils.md Normal file
View file

File diff suppressed because it is too large Load diff

1767
spec/11_special_systems.md Normal file
View file

File diff suppressed because it is too large Load diff

1903
spec/12_constants_types.md Normal file
View file

File diff suppressed because it is too large Load diff

1537
spec/13_rust_codebase.md Normal file
View file

File diff suppressed because it is too large Load diff

122
spec/INDEX.md Normal file
View file

@ -0,0 +1,122 @@
# Claude Code — Spec Index
> Quick-reference index across all spec documents.
> Total spec coverage: ~990 KB across 15 markdown files.
---
## Spec Files
| # | File | Size | What's Inside |
|---|------|------|---------------|
| — | [00_overview.md](00_overview.md) | 16 KB | Master architecture, repo structure, data flow, permission model, settings layers |
| 01 | [01_core_entry_query.md](01_core_entry_query.md) | 73 KB | `main.tsx`, `query.ts`, `QueryEngine.ts`, entry points, history, cost tracking, token budget |
| 02 | [02_commands.md](02_commands.md) | 71 KB | All 100+ slash commands with args, options, and implementation |
| 03 | [03_tools.md](03_tools.md) | 67 KB | All 40+ tools: input schemas, permissions, outputs, shared utilities |
| 04 | [04_components_core_messages.md](04_components_core_messages.md) | 93 KB | 130 top-level UI components + all message rendering components |
| 05 | [05_components_agents_permissions_design.md](05_components_agents_permissions_design.md) | 64 KB | Agent creation wizard, permission dialogs, design system, PromptInput, Spinner |
| 06 | [06_services_context_state.md](06_services_context_state.md) | 95 KB | Analytics, API client, session memory, autoDream, compact, voice, contexts, state |
| 07 | [07_hooks.md](07_hooks.md) | 84 KB | All 104 React hooks with params, return types, and behavior |
| 08 | [08_ink_terminal.md](08_ink_terminal.md) | 78 KB | Custom terminal framework: React reconciler, Yoga layout, screen buffer, ANSI tokenizer |
| 09 | [09_bridge_cli_remote.md](09_bridge_cli_remote.md) | 75 KB | Bridge protocol, JWT auth, SSE/WebSocket/Hybrid transports, remote sessions |
| 10 | [10_utils.md](10_utils.md) | 60 KB | ~564 utility files organized by category |
| 11 | [11_special_systems.md](11_special_systems.md) | 64 KB | Buddy/Tamagotchi, memdir, keybindings, skills, voice, plugins, migrations |
| 12 | [12_constants_types.md](12_constants_types.md) | 83 KB | Every constant, type, OAuth config, system prompts, tool limits, beta headers |
| 13 | [13_rust_codebase.md](13_rust_codebase.md) | 63 KB | Complete Rust rewrite: all 9 crates, 33 tools, query loop, TUI, bridge |
---
## Quick Lookup
### "Where is X documented?"
| Topic | Spec File | Section |
|-------|-----------|---------|
| Main entry point (`main.tsx`) | 01 | §1 |
| Query/turn execution loop | 01 | §2–3 |
| Token budget & compaction | 01 | §token-budget |
| Tool base class & framework | 03 | §1 |
| BashTool | 03 | §BashTool |
| FileEditTool | 03 | §FileEditTool |
| AgentTool (sub-agents) | 03 | §AgentTool |
| WebSearchTool | 03 | §WebSearchTool |
| MCPTool | 03 | §MCPTool |
| All slash commands | 02 | §per-command |
| `/compact` command | 02 | §compact |
| `/mcp` command | 02 | §mcp |
| `/plan` command | 02 | §plan |
| Permission dialog system | 05 | §permissions |
| Permission rules (settings) | 05 | §rules |
| PromptInput component | 05 | §PromptInput |
| Message rendering | 04 | §messages |
| Spinner component | 05 | §Spinner |
| Agent creation wizard | 05 | §agents |
| Claude API client | 06 | §api/claude |
| Analytics / telemetry | 06 | §analytics |
| Session memory | 06 | §SessionMemory |
| AutoDream consolidation | 06 | §autoDream |
| Rate limiting | 06 | §claudeAiLimits |
| Context compaction | 06 | §compact |
| React contexts | 06 | §context |
| Bootstrap state (80+ fields) | 06 | §bootstrap |
| Coordinator mode | 06 | §coordinator |
| All React hooks | 07 | §per-hook |
| Ink reconciler | 08 | §reconciler |
| Yoga layout engine | 08 | §layout |
| Screen buffer / rendering | 08 | §screen |
| ANSI/CSI/ESC handling | 08 | §termio |
| Bridge protocol | 09 | §bridge |
| JWT authentication | 09 | §jwtUtils |
| SSE transport | 09 | §SSETransport |
| WebSocket transport | 09 | §WebSocketTransport |
| Remote sessions | 09 | §remote |
| Buddy/Tamagotchi | 11 | §buddy |
| Gacha mechanics (PRNG) | 11 | §buddy-gacha |
| Memory directory system | 11 | §memdir |
| Keybinding parser | 11 | §keybindings |
| Skills system | 11 | §skills |
| Voice / STT | 11 | §voice |
| Plugin system | 11 | §plugins |
| Model migration history | 11 | §migrations |
| All constants | 12 | §constants |
| System prompt architecture | 12 | §prompts |
| OAuth configuration | 12 | §oauth |
| Beta feature headers | 12 | §betas |
| Cyber risk instruction | 12 | §cyberRisk |
| Tool name constants | 12 | §tools |
| All TypeScript types | 12 | §types |
| Rust rewrite overview | 13 | §1 |
| Rust tool implementations | 13 | §cc-tools |
| Rust query loop | 13 | §cc-query |
| Rust TUI | 13 | §cc-tui |
| Rust bridge | 13 | §cc-bridge |
---
## Key Numbers
| Metric | Value |
|--------|-------|
| Total TypeScript/TSX files | ~1,902 |
| Total lines of code | ~800K+ |
| Number of slash commands | 100+ |
| Number of tools | 40+ |
| Number of React hooks | 104 |
| Number of React components | 389 files |
| Number of services | 130 files |
| Number of utility files | ~564 |
| Ink terminal framework files | 96 |
| Bridge protocol files | 31 |
| Rust crates | 9 |
| Rust source files | 47 |
| Spec documentation size | ~990 KB |
---
## Architecture in One Paragraph
Claude Code is a terminal AI coding assistant built as a React application running in a custom terminal UI framework (Ink, a React reconciler targeting terminal output with Yoga flexbox layout). The main loop (`query.ts` + `QueryEngine.ts`) streams responses from the Claude API, executes tools with user permission, and manages a 200K-token context window with automatic compaction. It has 100+ slash commands, 40+ tools (file I/O, shell, web, agents, MCP), a multi-agent system for parallel task execution, a memory system for long-term context, voice input, IDE integration via a bridge protocol (WebSocket/SSE), and a plugin/skills marketplace. The codebase is being rewritten in Rust (`claude-code-rust/`) as a complete standalone reimplementation.
---
*Generated 2026-03-31 from Claude Code source analysis.*