hello world
This commit is contained in:
kuberwastaken
commit
c99507ca1e
84 changed files with 54252 additions and 0 deletions
334
spec/00_overview.md
Normal file
334
spec/00_overview.md
Normal 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.*
|
||||
Loading…
Add table
Add a link
Reference in a new issue