claude-code/spec/13_rust_codebase.md

# Claude Code — Rust Codebase

## Overview

The Rust codebase at `claude-code-rust/` is a **complete standalone rewrite** of the TypeScript Claude Code CLI in async Rust. It is not an FFI binding layer, not a partial port, and shares no runtime code with the TypeScript implementation. It re-implements the same tool names and semantics, permission model, CLAUDE.md discovery, auto-compact logic, MCP (Model Context Protocol) client, bridge protocol, and cron scheduler — all in async Rust using the Tokio runtime.

### Architecture

```
claude-code-rust/
├── Cargo.toml                  # Workspace root
└── crates/
    ├── core/       (cc-core)       # Shared types, config, permissions, history, hooks
    ├── api/        (cc-api)        # API client + SSE streaming
    ├── tools/      (cc-tools)      # All tool implementations (33 tools)
    ├── query/      (cc-query)      # Agentic query loop, compact, cron scheduler
    ├── tui/        (cc-tui)        # ratatui terminal UI
    ├── commands/   (cc-commands)   # Slash command implementations
    ├── mcp/        (cc-mcp)        # MCP (Model Context Protocol) client
    ├── bridge/     (cc-bridge)     # Bridge to claude.ai web UI
    └── cli/        (claude-code)   # Binary entry point
```

**Dependency flow:**
```
cli → query → tools → core
         ↓         ↗
        api  →  core
         ↓
       commands → core
         ↓
        tui   → core
         ↓
        mcp   → core
         ↓
       bridge → core
```

---

## Workspace Root: `Cargo.toml`

**Path:** `claude-code-rust/Cargo.toml`

Cargo workspace with `resolver = "2"`, edition `2021`, version `1.0.0` across all member crates.

### Workspace Members
| Member Path | Package Name | Type |
|---|---|---|
| `crates/core` | `cc-core` | Library |
| `crates/api` | `cc-api` | Library |
| `crates/tools` | `cc-tools` | Library |
| `crates/query` | `cc-query` | Library |
| `crates/tui` | `cc-tui` | Library |
| `crates/commands` | `cc-commands` | Library |
| `crates/mcp` | `cc-mcp` | Library |
| `crates/bridge` | `cc-bridge` | Library |
| `crates/cli` | `claude-code` | Binary (`[[bin]] name = "claude"`) |

### Key Shared Dependencies

| Crate | Version | Features |
|---|---|---|
| `tokio` | 1.44 | `full` |
| `reqwest` | 0.12 | `json`, `stream`, `rustls-tls` |
| `ratatui` | 0.29 | default |
| `crossterm` | 0.28 | `event-stream` |
| `clap` | 4 | `derive`, `env`, `string` |
| `serde` | 1 | `derive` |
| `serde_json` | 1 | default |
| `anyhow` | 1 | default |
| `thiserror` | 2 | default |
| `tracing` | 0.1 | default |
| `tracing-subscriber` | 0.3 | `env-filter` |
| `uuid` | 1 | `v4` |
| `chrono` | 0.4 | `serde` |
| `regex` | 1 | default |
| `glob` | 0.3 | default |
| `walkdir` | 2 | default |
| `similar` | 2 | default (declared, not heavily used) |
| `once_cell` | 1 | default |
| `parking_lot` | 0.12 | default |
| `dashmap` | 6 | default |
| `tokio-util` | 0.7 | `codec`, `sync` |
| `async-trait` | 0.1 | default |
| `schemars` | 0.8 | `derive` |
| `nix` | 0.29 | `process`, `signal`, `user` |
| `base64` | 0.22 | default |
| `sha2` | 0.10 | default |
| `hex` | 0.4 | default |

---

## Crate: `cc-core`

**Path:** `crates/core/src/lib.rs`

Central shared crate. Defines all types consumed by every other crate. Contains 9 inline submodules.

### Module: `error`

**`ClaudeError` enum** (implements `std::error::Error` via `thiserror`):
- `Api(String)` — Generic API error
- `ApiStatus { status_code: u16, message: String }` — HTTP status error
- `Auth(String)` — Authentication failure
- `PermissionDenied(String)` — Tool permission denied
- `Tool(String)` — Tool execution error
- `Io(#[from] std::io::Error)` — I/O error
- `Json(#[from] serde_json::Error)` — JSON parse error
- `Http(#[from] reqwest::Error)` — HTTP client error
- `RateLimit { retry_after: Option<u64> }` — 429 rate limit
- `ContextWindowExceeded` — Context window full
- `MaxTokensReached` — max_tokens hit
- `Cancelled` — User/signal cancellation
- `Config(String)` — Config load/save error
- `Mcp(String)` — MCP protocol error
- `Other(String)` — Catch-all

**Key methods:**
- `is_retryable(&self) -> bool` — true for `RateLimit` and `ApiStatus` with code 529
- `is_context_limit(&self) -> bool` — true for `ContextWindowExceeded` and `MaxTokensReached`

### Module: `types`

**`Role` enum:** `User`, `Assistant`

**`ContentBlock` enum** (serde untagged):
- `Text { text: String }`
- `Image { source: ImageSource }`
- `ToolUse { id: String, name: String, input: Value }`
- `ToolResult { tool_use_id: String, content: ToolResultContent, is_error: Option<bool> }`
- `Thinking { thinking: String, signature: String }`
- `RedactedThinking { data: String }`
- `Document { source: DocumentSource, citations: Option<CitationsConfig> }`

**`MessageContent` enum** (serde untagged):
- `Text(String)`
- `Blocks(Vec<ContentBlock>)`

**`Message` struct:**
- Fields: `role: Role`, `content: MessageContent`
- `Message::user(text)` — convenience constructor
- `Message::assistant(text)` — convenience constructor
- `Message::user_blocks(blocks: Vec<ContentBlock>)` — multi-block user message
- `Message::assistant_blocks(blocks)` — multi-block assistant message
- `get_text() -> Option<&str>` — first Text block or Text content
- `get_all_text() -> String` — concatenate all text blocks
- `get_tool_use_blocks() -> Vec<ContentBlock>` — filter ToolUse blocks
- `get_thinking_blocks() -> Vec<ContentBlock>` — filter Thinking blocks
- `has_tool_use() -> bool`
- `content_blocks() -> &[ContentBlock]`

**`UsageInfo` struct:**
- Fields: `input_tokens: u32`, `output_tokens: u32`, `cache_creation_input_tokens: u32`, `cache_read_input_tokens: u32`
- `total_input() -> u32` — sum of input + cache tokens
- `total() -> u32` — sum of all tokens
- Implements `Default`

**`ToolDefinition` struct:** `{ name: String, description: String, input_schema: Value }`

**Supporting types:** `MessageCost`, `ImageSource { type, media_type, data }`, `DocumentSource`, `CitationsConfig`, `ToolResultContent` (Text/Blocks enum)

### Module: `config`

**`Config` struct** — runtime configuration:
- `api_key: Option<String>`
- `api_base: Option<String>`
- `model: String`
- `max_tokens: u32`
- `permission_mode: PermissionMode`
- `verbose: bool`
- `output_format: OutputFormat`
- `max_turns: u32`
- `system_prompt: Option<String>`
- `append_system_prompt: Option<String>`
- `no_claude_md: bool`
- `auto_compact: bool`
- `thinking_budget: Option<u32>`
- `mcp_servers: Vec<McpServerConfig>`
- `hooks: HashMap<HookEvent, Vec<HookEntry>>`

**Key methods:**
- `resolve_api_key() -> Option<String>` — checks `config.api_key` then `ANTHROPIC_API_KEY` env var
- `resolve_api_base() -> String` — checks `ANTHROPIC_BASE_URL` env var, falls back to constant
- `effective_model() -> &str`
- `effective_max_tokens() -> u32`

**`PermissionMode` enum:**
- `Default` — allow read-only operations automatically
- `AcceptEdits` — allow all edits automatically
- `BypassPermissions` — allow everything without prompting
- `Plan` — read-only planning mode

**`OutputFormat` enum:** `Text`, `Json`, `StreamJson`

**`HookEvent` enum:** `PreToolUse`, `PostToolUse`, `Stop`, `UserPromptSubmit`, `Notification`

**`HookEntry` struct:** `{ command: String, tool_filter: Option<String>, blocking: bool }`

**`McpServerConfig` struct:** `{ name: String, command: String, args: Vec<String>, env: HashMap<String, String>, url: Option<String>, server_type: McpServerType }`

**`Settings` struct** — persisted user preferences at `~/.claude/settings.json`:
- `async fn load() -> Result<Settings>` — deserializes JSON, returns default on missing file
- `async fn save(&self) -> Result<()>` — serializes to JSON, creates parent dirs

### Module: `constants`

All constants are `pub const`:

| Constant | Value |
|---|---|
| `APP_NAME` | `"claude"` |
| `DEFAULT_MODEL` | `"claude-opus-4-6"` |
| `SONNET_MODEL` | `"claude-sonnet-4-6"` |
| `HAIKU_MODEL` | `"claude-haiku-4-5-20251001"` |
| `DEFAULT_MAX_TOKENS` | `32_000` |
| `MAX_TOKENS_HARD_LIMIT` | `65_536` |
| `DEFAULT_COMPACT_THRESHOLD` | `0.9` |
| `MAX_TURNS_DEFAULT` | `10` |
| `ANTHROPIC_API_BASE` | `"https://api.anthropic.com"` |
| `ANTHROPIC_API_VERSION` | `"2023-06-01"` |
| `ANTHROPIC_BETA_HEADER` | `"interleaved-thinking-2025-05-14,token-efficient-tools-2025-02-19,files-api-2025-04-14"` |
| `CLAUDE_MD_FILENAME` | `"CLAUDE.md"` |
| `SETTINGS_FILENAME` | `"settings.json"` |
| `HISTORY_FILENAME` | `"history.json"` |
| `CONFIG_DIR_NAME` | `".claude"` |

**Tool name constants:**
- `TOOL_NAME_BASH = "Bash"`
- `TOOL_NAME_FILE_EDIT = "Edit"`
- `TOOL_NAME_FILE_READ = "Read"`
- `TOOL_NAME_FILE_WRITE = "Write"`
- `TOOL_NAME_GLOB = "Glob"`
- `TOOL_NAME_GREP = "Grep"`
- `TOOL_NAME_WEB_FETCH = "WebFetch"`
- `TOOL_NAME_WEB_SEARCH = "WebSearch"`
- `TOOL_NAME_NOTEBOOK_EDIT = "NotebookEdit"`
- `TOOL_NAME_AGENT = "Task"` (sub-agent)
- `TOOL_NAME_TODO_WRITE = "TodoWrite"`
- `TOOL_NAME_ASK_USER = "AskUserQuestion"`
- `TOOL_NAME_ENTER_PLAN_MODE = "EnterPlanMode"`
- `TOOL_NAME_EXIT_PLAN_MODE = "ExitPlanMode"`
- `TOOL_NAME_POWERSHELL = "PowerShell"`
- `TOOL_NAME_SLEEP = "Sleep"`
- `TOOL_NAME_CRON_CREATE = "CronCreate"`
- `TOOL_NAME_CRON_DELETE = "CronDelete"`
- `TOOL_NAME_CRON_LIST = "CronList"`
- `TOOL_NAME_ENTER_WORKTREE = "EnterWorktree"`
- `TOOL_NAME_EXIT_WORKTREE = "ExitWorktree"`
- `TOOL_NAME_LIST_MCP_RESOURCES = "ListMcpResources"`
- `TOOL_NAME_READ_MCP_RESOURCE = "ReadMcpResource"`
- `TOOL_NAME_TOOL_SEARCH = "ToolSearch"`
- `TOOL_NAME_BRIEF = "Brief"`
- `TOOL_NAME_CONFIG = "Config"`
- `TOOL_NAME_SEND_MESSAGE = "SendMessage"`
- `TOOL_NAME_SKILL = "Skill"`

### Module: `context`

**`ContextBuilder`** — builds system context strings injected into the system prompt:

- `build_system_context(working_dir: &Path) -> String`
  - Platform (OS + architecture)
  - Current working directory
  - Git status (runs `git status --short`)
  - Last 5 git commits (runs `git log --oneline -5`)

- `build_user_context(working_dir: &Path, no_claude_md: bool) -> String`
  - Current date/time (from `chrono::Local::now()`)
  - CLAUDE.md discovery: walks from `working_dir` up to filesystem root, collecting any `CLAUDE.md` files; also reads `~/.claude/CLAUDE.md`
  - Returns concatenated content of all discovered CLAUDE.md files

### Module: `permissions`

**`PermissionDecision` enum:** `Allow`, `AllowPermanently`, `Deny`, `DenyPermanently`

**`PermissionRequest` struct:** `{ tool_name: String, description: String, details: Option<String>, is_read_only: bool }`

**`PermissionHandler` trait:**
- `check_permission(&self, tool_name: &str) -> PermissionDecision`
- `request_permission(&self, request: &PermissionRequest) -> PermissionDecision`

**`AutoPermissionHandler`** — automatic non-interactive handler:
- `BypassPermissions` → `Allow` all requests
- `AcceptEdits` → `Allow` all requests
- `Plan` → `Allow` only if `is_read_only == true`, else `Deny`
- `Default` → `Allow` only if `is_read_only == true`, else `Deny`

### Module: `history`

**`ConversationSession` struct:**
```
id: String (UUID v4)
created_at: DateTime<Utc>
updated_at: DateTime<Utc>
messages: Vec<Message>
model: String
title: Option<String>
working_dir: String
```

**Functions:**
- `save_session(session: &ConversationSession) -> Result<()>` — writes to `~/.claude/conversations/<id>.json`
- `load_session(id: &str) -> Result<Option<ConversationSession>>` — reads from path above
- `list_sessions() -> Result<Vec<ConversationSession>>` — reads all `.json` files in `~/.claude/conversations/`, sorts by `updated_at` descending
- `delete_session(id: &str) -> Result<()>` — removes the file

### Module: `cost`

**`ModelPricing` struct:** `{ input_per_mtok: f64, output_per_mtok: f64, cache_creation_per_mtok: f64, cache_read_per_mtok: f64 }`

**Pricing constants:**
| Model | Input ($/MTok) | Output ($/MTok) |
|---|---|---|
| `OPUS` | $15.00 | $75.00 |
| `SONNET` | $3.00 | $15.00 |
| `HAIKU` | $0.80 | $4.00 |

**`CostTracker` struct** — lock-free using `AtomicU64`:
- `input_tokens: AtomicU64`
- `output_tokens: AtomicU64`
- `cache_creation_tokens: AtomicU64`
- `cache_read_tokens: AtomicU64`
- `add_usage(input, output, cache_creation, cache_read)` — atomic adds
- `total_cost_usd(model: &str) -> f64` — loads atomics, looks up pricing by model substring match
- `summary(model: &str) -> String` — human-readable cost + token counts
- Implements `Default`

### Module: `hooks`

**`HookContext` struct:** `{ event: String, tool_name: Option<String>, tool_input: Option<Value>, tool_output: Option<String>, is_error: Option<bool>, session_id: Option<String> }`

**`HookOutcome` enum:** `Allowed`, `Blocked(String)`, `Modified(Value)`

**`run_hooks(hooks, event, context, working_dir) -> HookOutcome`** (async):
- Iterates `Vec<HookEntry>` for the given `HookEvent`
- Applies `tool_filter` (glob match against `tool_name`)
- Spawns shell command via `tokio::process::Command`
- Sends `HookContext` as JSON on stdin
- If `blocking: true` and exit code != 0, returns `HookOutcome::Blocked(stderr)`
- Otherwise returns `HookOutcome::Allowed`

### Relationship to TypeScript

`cc-core` corresponds to the scattered TypeScript files: `src/constants/`, `src/context.ts`, `src/history.ts`, `src/cost-tracker.ts`, `src/costHook.ts`, `src/schemas/hooks.ts`, and parts of `src/services/api/`. The permission modes, hook events, and config structure mirror the TypeScript `Config` type exactly.

---

## Crate: `cc-api`

**Path:** `crates/api/src/lib.rs`

Complete async Messages API client with SSE streaming support.

### Module: `types`

**`CreateMessageRequest` struct:** built via `CreateMessageRequestBuilder`:
- `model: String`
- `max_tokens: u32`
- `messages: Vec<ApiMessage>`
- `system: Option<SystemPrompt>`
- `tools: Option<Vec<ApiToolDefinition>>`
- `temperature: Option<f32>`
- `top_p: Option<f32>`
- `top_k: Option<u32>`
- `stop_sequences: Option<Vec<String>>`
- `thinking: Option<ThinkingConfig>`
- `stream: bool` (always set to `true` internally)

**`CreateMessageRequestBuilder`** — fluent builder:
- `CreateMessageRequest::builder(model, max_tokens) -> Self`
- `.messages(Vec<ApiMessage>)`
- `.system(SystemPrompt)` or `.system_text(String)`
- `.tools(Vec<ApiToolDefinition>)`
- `.temperature(f32)`, `.top_p(f32)`, `.top_k(u32)`
- `.stop_sequences(Vec<String>)`
- `.thinking(ThinkingConfig)`
- `.build() -> CreateMessageRequest`

**`ThinkingConfig`:** `{ type: "enabled", budget_tokens: u32 }`
- `ThinkingConfig::enabled(budget: u32) -> Self`

**`SystemPrompt` enum** (serde untagged):
- `Text(String)` — simple text system prompt
- `Blocks(Vec<SystemBlock>)` — structured blocks with cache control

**`SystemBlock`:** `{ type: "text", text: String, cache_control: Option<CacheControl> }`

**`CacheControl`:** `{ type: "ephemeral" }`
- `CacheControl::ephemeral() -> Self`

**`ApiMessage`:** `{ role: String, content: Value }`
- `From<&Message> for ApiMessage` — converts `cc_core::types::Message` to API format

**`ApiToolDefinition`:** `{ name: String, description: String, input_schema: Value, cache_control: Option<CacheControl> }`
- `From<&ToolDefinition> for ApiToolDefinition`
- Last tool in the list gets `cache_control: Some(CacheControl::ephemeral())` (prompt caching)

**`CreateMessageResponse`:** `{ id, type, role, content, model, stop_reason, stop_sequence, usage }`

**`ApiErrorResponse`:** `{ type: String, error: ApiErrorDetail }`

### Module: `streaming`

**`StreamEvent` enum** (serde `#[serde(tag = "type")]`):
- `MessageStart { message: CreateMessageResponse }`
- `MessageDelta { delta: MessageDeltaData, usage: Option<StreamUsage> }`
- `MessageStop`
- `ContentBlockStart { index: usize, content_block: PartialContentBlock }`
- `ContentBlockDelta { index: usize, delta: ContentDelta }`
- `ContentBlockStop { index: usize }`
- `Ping`
- `Error { error_type: String, message: String }`

**`ContentDelta` enum:**
- `TextDelta { text: String }`
- `InputJsonDelta { partial_json: String }`
- `ThinkingDelta { thinking: String }`
- `SignatureDelta { signature: String }`

**`StreamHandler` trait:**
- `fn on_event(&self, event: &StreamEvent)` — called for each SSE event

**`NullStreamHandler`** — no-op implementation for headless mode

**`StreamAccumulator`** — collects stream events into a complete message:
- `on_event(&mut self, event: &StreamEvent)` — processes all event types
- `finish(self) -> (Message, UsageInfo, Option<String>)` — returns (assistant_message, usage, stop_reason)

Internal `PartialBlock` enum during accumulation:
- `Text(String)`
- `ToolUse { id: String, name: String, json_buf: String }`
- `Thinking { thinking_buf: String, signature_buf: String }`

### Module: `sse_parser`

**`SseFrame` struct:** `{ event: Option<String>, data: Option<String> }`

**`SseLineParser`** — stateful line-by-line SSE parser:
- `feed_line(&mut self, line: &str) -> Option<SseFrame>`
- Handles `event:`, `data:`, and blank-line frame boundaries per SSE spec

### Module: `client`

**`ClientConfig` struct:**
- `api_key: String`
- `api_base: String` (default: `ANTHROPIC_API_BASE`)
- `timeout_secs: u64` (default: 600)
- `max_retries: u32` (default: 5)

**`AnthropicClient` struct:**
- `AnthropicClient::new(config: ClientConfig) -> Result<Self>` — validates API key, builds `reqwest::Client` with rustls-tls, sets `anthropic-version` and `anthropic-beta` headers
- `AnthropicClient::from_config(cfg: &Config) -> Result<Self>` — resolves key/base from Config

**`create_message(request) -> Result<CreateMessageResponse>`** — non-streaming POST to `/v1/messages`

**`create_message_stream(request, handler) -> Result<mpsc::Receiver<StreamEvent>>`** (async):
1. Sets `stream: true` on request
2. Spawns `tokio::spawn` background task calling `process_sse_stream()`
3. Returns `mpsc::Receiver<StreamEvent>` with channel buffer 256
4. Background task reads response body line by line via `SseLineParser`
5. Calls `frame_to_event()` to parse each frame
6. Sends to channel + calls `handler.on_event()`

**`send_with_retry(request_fn) -> Result<reqwest::Response>`** — exponential backoff:
- Max 5 retries
- Initial delay: 1 second
- Multiplier: 2× per retry, capped at 60 seconds
- Honors `Retry-After` response header (overrides backoff delay)
- Retries on 429 (`RateLimit`) and 529 (`ApiStatus` overloaded)

**`frame_to_event(frame: SseFrame) -> Option<StreamEvent>`** — dispatches by `frame.event`:
- `"ping"` → `StreamEvent::Ping`
- `"message_start"` → deserialize `data` into `StreamEvent::MessageStart`
- `"content_block_start"` → `StreamEvent::ContentBlockStart`
- `"content_block_delta"` → `StreamEvent::ContentBlockDelta`
- `"content_block_stop"` → `StreamEvent::ContentBlockStop`
- `"message_delta"` → `StreamEvent::MessageDelta`
- `"message_stop"` → `StreamEvent::MessageStop`
- `"error"` → `StreamEvent::Error`

### Relationship to TypeScript

Corresponds to `src/services/api/claude.ts`, `src/services/api/client.ts`, and `src/services/api/errorUtils.ts`. Implements the same SSE streaming protocol and retry logic. Prompt caching via `CacheControl::ephemeral()` mirrors the TypeScript cache control implementation. Beta header is identical.

---

## Crate: `cc-tools`

**Path:** `crates/tools/src/`

Implements all 33 built-in tools. Each tool is a zero-sized struct implementing the `Tool` trait.

### Core Types (`lib.rs`)

**`ToolResult` struct:**
- `content: String`
- `is_error: bool`
- `metadata: Option<Value>` — optional structured data for TUI rendering
- `ToolResult::success(content)` / `ToolResult::error(content)` / `.with_metadata(meta)`

**`PermissionLevel` enum:** `None`, `ReadOnly`, `Write`, `Execute`, `Dangerous`

**`ToolContext` struct:**
- `working_dir: PathBuf`
- `permission_mode: PermissionMode`
- `permission_handler: Arc<dyn PermissionHandler>`
- `cost_tracker: Arc<CostTracker>`
- `session_id: String`
- `non_interactive: bool`
- `mcp_manager: Option<Arc<cc_mcp::McpManager>>`
- `config: cc_core::config::Config`
- `resolve_path(&self, path: &str) -> PathBuf` — resolves relative paths against `working_dir`
- `check_permission(tool_name, description, is_read_only) -> Result<(), ClaudeError>`

**`Tool` trait** (async_trait):
- `fn name(&self) -> &str`
- `fn description(&self) -> &str`
- `fn permission_level(&self) -> PermissionLevel`
- `fn input_schema(&self) -> Value` — JSON Schema for tool parameters
- `async fn execute(&self, input: Value, ctx: &ToolContext) -> ToolResult`
- `fn to_definition(&self) -> ToolDefinition` — default impl from above methods

**`all_tools() -> Vec<Box<dyn Tool>>`** — returns all 33 tools

**`find_tool(name: &str) -> Option<Box<dyn Tool>>`** — finds by exact name match

### Tool: `BashTool` (`bash.rs`)

**Name:** `"Bash"`
**Permission level:** `Execute`

Input schema: `{ command: string, timeout: optional u64 (seconds) }`

**Algorithm:**
1. Checks permission via `ctx.check_permission()`
2. On Windows: `cmd /C <command>`. On Unix: `bash -c <command>`
3. Default timeout: 120 seconds. Maximum: 600 seconds
4. Collects stdout and stderr with `tokio::io::BufReader`
5. Truncates output >100,000 characters with notice
6. Non-zero exit → `ToolResult::error` with combined stdout+stderr+exit_code
7. Zero exit → `ToolResult::success` with stdout (stderr appended if non-empty)

### Tool: `FileReadTool` (`file_read.rs`)

**Name:** `"Read"`
**Permission level:** `ReadOnly`

Input schema: `{ file_path: string, offset: optional u32 (1-based line), limit: optional u32 }`

**Algorithm:**
1. Resolves path via `ctx.resolve_path()`
2. Default limit: 2000 lines
3. Reads entire file, splits on newlines
4. Applies offset (1-based) and limit
5. Formats output as `{line_number}\t{content}`
6. Returns error on binary files (detected via `std::io::ErrorKind::InvalidData`)
7. Returns stub message for images and PDFs

### Tool: `FileEditTool` (`file_edit.rs`)

**Name:** `"Edit"`
**Permission level:** `Write`

Input schema: `{ file_path: string, old_string: string, new_string: string, replace_all: optional bool }`

**Algorithm:**
1. Validates `old_string != new_string`
2. Reads current file content
3. Counts occurrences of `old_string`
4. If `replace_all == false` (default) and count > 1: returns error (ambiguous)
5. If `replace_all == true`: uses `str::replace()` (replaces all)
6. If `replace_all == false` and count == 1: uses `str::replacen(old, new, 1)`
7. Writes updated content back to file

### Tool: `FileWriteTool` (`file_write.rs`)

**Name:** `"Write"`
**Permission level:** `Write`

Input schema: `{ file_path: string, content: string }`

**Algorithm:**
1. Resolves path
2. Creates parent directories via `tokio::fs::create_dir_all()`
3. Writes content to file
4. Reports line count and byte count in success message

### Tool: `GlobTool` (`glob_tool.rs`)

**Name:** `"Glob"`
**Permission level:** `ReadOnly`

Input schema: `{ pattern: string, path: optional string }`

**Algorithm:**
1. Resolves base path (defaults to `working_dir`)
2. Constructs full glob pattern by joining base + pattern
3. Uses `glob::glob()` crate for pattern matching
4. Sorts results by modification time (most recent first)
5. Returns max 250 results
6. Returns newline-separated list of relative paths

### Tool: `GrepTool` (`grep_tool.rs`)

**Name:** `"Grep"`
**Permission level:** `ReadOnly`

Input schema: `{ pattern: string, path: optional string, glob: optional string, type: optional string, output_mode: optional enum, context: optional u32, head_limit: optional u32, offset: optional u32, -i: optional bool, -n: optional bool, -A: optional u32, -B: optional u32, -C: optional u32, multiline: optional bool }`

**Algorithm:**
1. Compiles `RegexBuilder` with `case_insensitive` and `multi_line` flags
2. Uses `walkdir::WalkDir` to traverse directory tree
3. Skips hidden directories, `node_modules/`, `target/`, `__pycache__/`, `.git/`
4. Filters by glob pattern or file type extension mapping
5. Three output modes:
   - `files_with_matches` — list of file paths (default)
   - `content` — matching lines with optional context (-A/-B/-C)
   - `count` — match counts per file
6. Applies `head_limit` and `offset` pagination

**Type shortcuts** (e.g., `type="js"` → `["js", "jsx", "mjs", "cjs"]`):
- `js`, `ts`, `py`, `rs`, `go`, `java`, `rb`, `cpp`, `c`, `cs`, `php`, `swift`, `kt`, `html`, `css`, `json`, `yaml`, `md`

### Tool: `WebFetchTool` (`web_fetch.rs`)

**Name:** `"WebFetch"`
**Permission level:** `ReadOnly`

Input schema: `{ url: string, prompt: optional string }`

**Algorithm:**
1. `reqwest` GET with 30-second timeout, 10 redirect limit
2. User-Agent: `"Claude-Code/1.0"`
3. If HTML content-type: runs `strip_html()` — manual state machine removing tags, scripts, styles; converts `&amp;`, `&lt;`, `&gt;`, `&nbsp;` entities
4. Truncates content >100,000 characters
5. Returns text content

### Tool: `WebSearchTool` (`web_search.rs`)

**Name:** `"WebSearch"`
**Permission level:** `ReadOnly`

Input schema: `{ query: string, num_results: optional u32 (default 5) }`

**Algorithm:**
1. Checks `BRAVE_SEARCH_API_KEY` env var:
   - If set: calls Brave Search API at `https://api.search.brave.com/res/v1/web/search`
   - Returns title + URL + description for each result
2. Fallback: DuckDuckGo Instant Answer API at `https://api.duckduckgo.com/?q=...&format=json`
3. Returns up to `num_results` formatted results

### Tool: `NotebookEditTool` (`notebook_edit.rs`)

**Name:** `"NotebookEdit"`
**Permission level:** `Write`

Input schema: `{ notebook_path: string, cell_id: optional string, cell_index: optional u32, source: optional string, cell_type: optional string, mode: string (replace|insert|delete) }`

**Algorithm:**
1. Parses `.ipynb` JSON with `serde_json`
2. Cell lookup: by UUID string OR by `cell-N` index pattern
3. **replace mode:** updates `source`, resets `outputs = []`, `execution_count = null`
4. **insert mode:** inserts new cell at given index or after cell_id; generates 8-char hex cell ID from `timestamp XOR random`
5. **delete mode:** removes cell by id/index
6. Writes updated notebook back to file

### Tool: `TaskCreateTool`, `TaskGetTool`, `TaskUpdateTool`, `TaskListTool`, `TaskStopTool`, `TaskOutputTool` (`tasks.rs`)

Global store: `TASK_STORE: Lazy<Arc<DashMap<String, Task>>>`

**`Task` struct:** `{ id: String, subject: String, description: String, status: TaskStatus, owner: Option<String>, blocks: Vec<String>, blocked_by: Vec<String>, metadata: HashMap<String, Value>, output: Vec<String>, created_at: DateTime<Utc>, updated_at: DateTime<Utc> }`

**`TaskStatus` enum:** `Pending`, `InProgress`, `Completed`, `Deleted`, `Running`, `Failed`

| Tool | Name | Description |
|---|---|---|
| `TaskCreateTool` | `"TaskCreate"` | Creates task with UUID, stores in `TASK_STORE` |
| `TaskGetTool` | `"TaskGet"` | Returns task JSON by ID |
| `TaskUpdateTool` | `"TaskUpdate"` | Updates task fields; `status=deleted` removes from store |
| `TaskListTool` | `"TaskList"` | Lists all non-deleted tasks with optional status filter |
| `TaskStopTool` | `"TaskStop"` | Sets task status to `Failed` |
| `TaskOutputTool` | `"TaskOutput"` | Appends text to task `output` vector |

### Tool: `CronCreateTool`, `CronDeleteTool`, `CronListTool` (`cron.rs`)

Global store: `CRON_STORE: Lazy<Arc<RwLock<HashMap<String, CronTask>>>>`

**`CronTask` struct:** `{ id: String, cron: String, prompt: String, recurring: bool, durable: bool, created_at: DateTime<Utc> }`

| Tool | Name | Description |
|---|---|---|
| `CronCreateTool` | `"CronCreate"` | Creates scheduled task; validates cron expression; if `durable=true`, persists to `.claude/scheduled_tasks.json`; max 50 jobs |
| `CronDeleteTool` | `"CronDelete"` | Removes task by ID from store (and disk if durable) |
| `CronListTool` | `"CronList"` | Lists all scheduled tasks with human-readable schedule |

**`cron_matches(cron: &str, now: &DateTime<Local>) -> bool`:**
- Parses 5-field cron: minute, hour, day-of-month, month, day-of-week
- Supports: `*`, `*/N` (step), `N-M` (range), `N,M,...` (list)

**`validate_cron(cron: &str) -> Result<()>`** — validates field ranges (minute 0–59, hour 0–23, etc.)

**`cron_to_human(cron: &str) -> String`** — describes schedule in plain English

**`pop_due_tasks() -> Vec<CronTask>`** — returns tasks matching current time, removes non-recurring tasks from store

### Tool: `TodoWriteTool` (`todo_write.rs`)

**Name:** `"TodoWrite"`
**Permission level:** `None`

Input schema: `{ todos: Array<{ id: string, content: string, status: string, priority: string }> }`

Replaces entire todo list. Returns summary with counts of pending/in_progress/completed items.

### Tool: `AskUserQuestionTool` (`ask_user.rs`)

**Name:** `"AskUserQuestion"`
**Permission level:** `None`

Input schema: `{ question: string, options: optional Array<string> }`

In `non_interactive` mode: returns error "Cannot prompt user in non-interactive mode".
Otherwise: returns `ToolResult::success("")` with metadata `{ type: "ask_user", question, options }` for TUI layer to handle.

### Tool: `EnterPlanModeTool` (`enter_plan_mode.rs`)

**Name:** `"EnterPlanMode"`
**Permission level:** `None`

Returns `ToolResult::success` with metadata `{ type: "enter_plan_mode" }`. Signals the session to switch to Plan permission mode.

### Tool: `ExitPlanModeTool` (`exit_plan_mode.rs`)

**Name:** `"ExitPlanMode"`
**Permission level:** `None`

Input schema: `{ summary: optional string }`

Returns success with metadata `{ type: "exit_plan_mode", summary }`. Signals return from Plan mode.

### Tool: `PowerShellTool` (`powershell.rs`)

**Name:** `"PowerShell"`
**Permission level:** `Execute`

Input schema: `{ command: string, timeout: optional u64 }`

Same execution pattern as `BashTool`. On Windows uses `powershell -NoProfile -NonInteractive -Command`. On other platforms uses `pwsh`.

### Tool: `EnterWorktreeTool`, `ExitWorktreeTool` (`worktree.rs`)

Global: `WORKTREE_SESSION: Lazy<Arc<RwLock<Option<WorktreeSession>>>>`

**`WorktreeSession`:** `{ branch: String, path: PathBuf, original_dir: PathBuf }`

**`EnterWorktreeTool`** (`"EnterWorktree"`):
- Input: `{ branch: string, path: optional string }`
- Runs `git worktree add -b <branch> <path>`
- Saves session to `WORKTREE_SESSION`

**`ExitWorktreeTool`** (`"ExitWorktree"`):
- Input: `{ action: "keep" | "remove", discard_changes: optional bool }`
- `keep`: locks worktree, clears session
- `remove`: checks for uncommitted changes (requires `discard_changes=true` to override), runs `git worktree remove --force <path>`, then `git branch -D <branch>`

### Tool: `SendMessageTool` (`send_message.rs`)

**Name:** `"SendMessage"`
**Permission level:** `None`

Global: `INBOX: Lazy<DashMap<String, Vec<AgentMessage>>>`

Input schema: `{ to: string, message: string, metadata: optional Value }`

- Delivers message to named recipient in `INBOX`
- `to = "*"` broadcasts to all existing keys
- `drain_inbox(recipient: &str) -> Vec<AgentMessage>` — removes and returns all messages
- `peek_inbox(recipient: &str) -> Vec<AgentMessage>` — returns without removing

### Tool: `SkillTool` (`skill_tool.rs`)

**Name:** `"Skill"`
**Permission level:** `None`

Input schema: `{ skill: string, arguments: optional string }`

**Algorithm:**
1. `skill = "list"` → enumerates `.claude/commands/*.md` and `~/.claude/commands/*.md`, extracts description from YAML frontmatter or first heading
2. Otherwise: resolves `<skill>.md` file from project then user commands directory
3. Strips YAML frontmatter (`---` block)
4. Substitutes `$ARGUMENTS` with provided arguments string
5. Returns file content as `ToolResult::success`

### Tool: `SleepTool` (`sleep.rs`)

**Name:** `"Sleep"`
**Permission level:** `None`

Input schema: `{ duration: f64 (seconds) }`

Calls `tokio::time::sleep(Duration::from_secs_f64(duration))`. Maximum 300 seconds.

### Tool: `ToolSearchTool` (`tool_search.rs`)

**Name:** `"ToolSearch"`
**Permission level:** `None`

Input schema: `{ query: string, max_results: optional u32 (default 5) }`

Static `TOOL_CATALOG: &[(&str, &str, &[&str])]` — 32 entries of `(name, description, keywords)`.

**Scoring algorithm:**
- `select:Name` syntax → score 100 for exact name match
- Otherwise for each catalog entry:
  - exact name match: +20
  - name contains query: +10
  - description contains query: +5
  - keyword exact match: +8
  - keyword contains query: +3
- Returns top `max_results` entries with non-zero score

### Tool: `BriefTool` (`brief.rs`)

**Name:** `"Brief"`
**Permission level:** `None`

Input schema: `{ message: string, status: optional string, attachments: optional Array<string> (file paths) }`

Resolves attachment metadata (file size, is_image flag from extension). Returns `ToolResult::success("")` with metadata `{ message, status, sentAt, attachments: [{ path, size, isImage }] }`.

### Tool: `ConfigTool` (`config_tool.rs`)

**Name:** `"Config"`
**Permission level:** `None`

Input schema: `{ action: "get" | "set", key: string, value: optional Value }`

Reads/writes `~/.claude/settings.json`. Supported keys: `model`, `max_tokens`, `verbose`, `permission_mode`, `auto_compact`. Returns current value on `get`, writes and confirms on `set`.

### Tool: `ListMcpResourcesTool`, `ReadMcpResourceTool` (`mcp_resources.rs`)

| Tool | Name | Description |
|---|---|---|
| `ListMcpResourcesTool` | `"ListMcpResources"` | Calls `ctx.mcp_manager.list_all_resources()`, returns JSON |
| `ReadMcpResourceTool` | `"ReadMcpResource"` | Input: `{ uri: string }`. Calls `ctx.mcp_manager.read_resource(uri)` |

Both return error if `ctx.mcp_manager` is `None`.

### Relationship to TypeScript

`cc-tools` corresponds to the TypeScript tool implementations in `src/` (e.g., bash is in the tool system, file operations in ReadTool/EditTool/WriteTool, etc.). Tool names are identical to the TypeScript constants. The `ToolContext` mirrors the TypeScript `ToolUseContext`.

---

## Crate: `cc-query`

**Path:** `crates/query/src/`

The core agentic query loop crate. Contains 4 source files.

### Module: `lib.rs` — Main Query Loop

**`QueryOutcome` enum:**
- `EndTurn { message: Message, usage: UsageInfo }` — model issued `end_turn`
- `MaxTokens { partial_message: Message, usage: UsageInfo }` — hit token limit
- `Cancelled` — cancellation token fired
- `Error(ClaudeError)` — unrecoverable error

**`QueryConfig` struct:**
- `model: String`
- `max_tokens: u32`
- `max_turns: u32` (default: `MAX_TURNS_DEFAULT = 10`)
- `system_prompt: Option<String>`
- `append_system_prompt: Option<String>`
- `thinking_budget: Option<u32>`
- `temperature: Option<f32>`
- `QueryConfig::default()` uses `DEFAULT_MODEL` + `DEFAULT_MAX_TOKENS`
- `QueryConfig::from_config(cfg: &Config)` — reads model + max_tokens from Config

**`QueryEvent` enum:**
- `Stream(StreamEvent)` — raw API stream event
- `ToolStart { tool_name, tool_id }` — tool beginning execution
- `ToolEnd { tool_name, tool_id, result, is_error }` — tool completed
- `TurnComplete { turn: u32, stop_reason: String }` — model turn finished
- `Status(String)` — informational message
- `Error(String)` — error notification

**`run_query_loop(client, messages, tools, tool_ctx, config, cost_tracker, event_tx, cancel_token) -> QueryOutcome`** (async):

Main agentic loop:
1. Increments turn counter; returns `EndTurn` if `> max_turns`
2. Checks `cancel_token.is_cancelled()` → `Cancelled`
3. Converts `messages` → `Vec<ApiMessage>`, tools → `Vec<ApiToolDefinition>`
4. Calls `build_system_prompt(config)` to construct `SystemPrompt`
5. Builds `CreateMessageRequest` (with thinking config if `budget` provided)
6. Creates `ChannelStreamHandler` or `NullStreamHandler`
7. Calls `client.create_message_stream()`, receives `mpsc::Receiver<StreamEvent>`
8. Inner loop: `tokio::select!` on cancellation or stream events; feeds `StreamAccumulator`
9. On `MessageStop` or channel close: calls `accumulator.finish()`
10. Tracks costs via `cost_tracker.add_usage()`
11. Appends assistant message to `messages`
12. Calls `auto_compact_if_needed()` if stop reason is `end_turn` or `tool_use`
13. Dispatches on `stop_reason`:
    - `"end_turn"` / `"stop_sequence"` / unknown → fires `Stop` hook → returns `EndTurn`
    - `"max_tokens"` → returns `MaxTokens`
    - `"tool_use"` → executes all tool_use blocks (see below), appends results, `continue`

**Tool execution in `tool_use` turn:**
1. For each `ContentBlock::ToolUse { id, name, input }`:
2. Emits `QueryEvent::ToolStart`
3. Fires `PreToolUse` hooks via `cc_core::hooks::run_hooks()`; if `HookOutcome::Blocked` → `ToolResult::error("Blocked by hook: ...")`
4. Otherwise calls `execute_tool(name, input, tools, ctx)`
5. Fires `PostToolUse` hooks
6. Emits `QueryEvent::ToolEnd`
7. Pushes `ContentBlock::ToolResult` to result_blocks
8. Appends `Message::user_blocks(result_blocks)` to conversation

**`execute_tool(name, input, tools, ctx) -> ToolResult`** (async):
- Finds tool by name in slice, calls `tool.execute(input, ctx)`
- Unknown tool → `ToolResult::error("Unknown tool: {name}")`

**`build_system_prompt(config) -> SystemPrompt`:**
- Joins `system_prompt` and `append_system_prompt` with `\n\n`
- Empty → default `"You are Claude, an AI assistant by Anthropic."`

**`run_single_query(client, messages, config) -> Result<Message>`** (async):
- Single API call, no tool loop, `NullStreamHandler`
- Returns complete assistant message

**`ChannelStreamHandler`** — implements `StreamHandler`:
- `on_event(&self, event)` forwards to `mpsc::UnboundedSender<QueryEvent>`

### Module: `compact.rs` — Auto-Compact

**Constants:**
- `AUTOCOMPACT_BUFFER_TOKENS = 13_000`
- `WARNING_THRESHOLD_BUFFER_TOKENS = 20_000`
- `AUTOCOMPACT_TRIGGER_FRACTION = 0.90`
- `KEEP_RECENT_MESSAGES = 10`
- `MAX_CONSECUTIVE_FAILURES = 3`

**`AutoCompactState` struct:**
- `compaction_count: u32`
- `consecutive_failures: u32`
- `disabled: bool` — circuit breaker; set after 3 consecutive failures

**`TokenWarningState` enum:** `Ok`, `Warning`, `Critical`

**`context_window_for_model(model: &str) -> u32`:**
- `200_000` for models matching "opus-4", "sonnet-4", "haiku-4", "claude-3-5"
- `100_000` otherwise

**`calculate_token_warning_state(input_tokens, model) -> TokenWarningState`:**
- Uses `WARNING_THRESHOLD_BUFFER_TOKENS` to determine Warning vs Critical

**`should_auto_compact(state, input_tokens, model) -> bool`:**
- Returns false if `state.disabled`
- Returns true if `input_tokens / context_window > AUTOCOMPACT_TRIGGER_FRACTION`

**`summarise_head(client, messages_to_summarize, model) -> Result<String>`** (async):
- Calls API with prompt asking to summarize the provided conversation
- Returns summary wrapped in `<compact-summary>...</compact-summary>` XML tags

**`compact_conversation(client, messages, model) -> Result<Vec<Message>>`** (async):
- Splits conversation: head = `messages[0..total-KEEP_RECENT_MESSAGES]`, tail = last 10 messages
- Calls `summarise_head()` on head
- Returns `[Message::user(summary)] + tail`

**`auto_compact_if_needed(client, messages, input_tokens, model, state) -> Option<Vec<Message>>`** (async):
- Checks `should_auto_compact()`, calls `compact_conversation()`
- On success: resets `consecutive_failures`, increments `compaction_count`
- On failure: increments `consecutive_failures`; disables if `>= MAX_CONSECUTIVE_FAILURES`
- Returns `Some(new_messages)` on success, `None` if not needed or failed

### Module: `agent_tool.rs` — Sub-Agent Tool

**`AgentTool`** implements `Tool`:
- **Name:** `"Task"` (constant `TOOL_NAME_AGENT`)
- **Permission level:** `Execute`

Input schema: `{ description: string, prompt: string, tools: optional Array<string>, system_prompt: optional string, max_turns: optional u32, model: optional string }`

**Algorithm:**
1. Creates dedicated `AnthropicClient` from `ANTHROPIC_API_KEY` env var
2. Filters tool list: if `tools` field provided, uses that subset; always excludes `TOOL_NAME_AGENT` (prevents recursion)
3. Calls `run_query_loop()` with:
   - `event_tx = None` (no TUI forwarding for sub-agent)
   - New `ToolContext` with same working_dir, permission_mode, etc.
4. Returns final assistant message text as `ToolResult::success()`

### Module: `cron_scheduler.rs` — Background Cron

**`start_cron_scheduler(tools, tool_ctx, cancel_token) -> JoinHandle<()>`:**
- Spawns `tokio::spawn(run_scheduler_loop(...))`

**`run_scheduler_loop(tools, tool_ctx, cancel_token)`** (async loop):
1. Computes seconds until next minute boundary: `sleep(60 - now.second() + 1)`
2. Calls `cc_tools::cron::pop_due_tasks()` to get matching tasks
3. For each due task: spawns `run_query_loop()` with:
   - Single user message from `task.prompt`
   - `event_tx = None` (background, no UI)
   - `cancel_token` clone
4. Loop continues until cancellation

### Relationship to TypeScript

`cc-query` corresponds to `src/query.ts`, `src/query/`, `src/services/compact/autoCompact.ts`, `src/coordinator/`, and parts of `src/services/autoDream/`. The `AgentTool` corresponds to the TypeScript `Task` tool.

---

## Crate: `cc-tui`

**Path:** `crates/tui/src/lib.rs`

Terminal UI built on `ratatui` + `crossterm`. Replaces the TypeScript `ink`/React rendering layer.

### `App` struct

```
config: Config
cost_tracker: Arc<CostTracker>
messages: Vec<(Role, String)>
input: String
input_history: Vec<String>
history_index: Option<usize>
scroll_offset: u16
is_streaming: bool
streaming_text: String
status_message: Option<String>
should_quit: bool
show_help: bool
```

### Key Methods

**`handle_key_event(&mut self, key: KeyEvent) -> Option<String>`:**
- `Ctrl+C`: if streaming → cancels; if input empty → quits; else clears input
- `Ctrl+D`: if input empty → quits
- Character input: appended to `self.input`
- `Backspace`: removes last char from `self.input`
- `Enter`: returns `Some(input)` for caller to process (empty input ignored)
- `Up`/`Down`: navigates `input_history`
- `PageUp`/`PageDown`: adjusts `scroll_offset`
- `F1` / `?`: toggles help overlay

**`handle_query_event(&mut self, event: QueryEvent)`:**
- `Stream(ContentBlockDelta::TextDelta)` → appends to `streaming_text`
- `ToolStart { tool_name, .. }` → sets `status_message = "Running {tool_name}..."`
- `ToolEnd { .. }` → clears `status_message`
- `TurnComplete { .. }` → moves `streaming_text` into `messages`, clears streaming state
- `Status(msg)` → sets `status_message`
- `Error(msg)` → sets `status_message` with error prefix

**`take_input(&mut self) -> String`:**
- Returns and clears `self.input`
- Pushes to `input_history` (dedup at head)

**`add_message(&mut self, role: Role, text: String)`** — appends to messages vec

### Module: `render`

**`render_app(f: &mut Frame, app: &App)`:**
- Splits terminal into 3 vertical chunks via `Layout::vertical`:
  1. Messages area (flex fill)
  2. Input area (3 rows)
  3. Status bar (1 row)
- **Messages:** renders each `(role, text)` pair — `Role::User` in Cyan, `Role::Assistant` in Green. If streaming, appends partial `streaming_text` in Yellow italic
- **Input area:** bordered `Block` titled "Input"; shows `self.input` with cursor `_` appended
- **Status bar:** shows `{model} | {cost_summary}` in Dark Gray

### Module: `widgets`

**`render_permission_dialog(f: &mut Frame, question: &str, options: &[String])`:**
- Centered popup dialog
- Shows question text
- Lists numbered options
- Renders as `Clear` + `Block` + `Paragraph` overlay

**`render_spinner(f: &mut Frame, area: Rect, frame_count: u64)`:**
- Cycles through braille spinner characters: `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`
- Indexed by `frame_count % 10`

### Module: `input`

**`is_slash_command(input: &str) -> bool`** — returns true if starts with `"/"`

**`parse_slash_command(input: &str) -> (&str, &str)`** — splits `"/name args"` → `("name", "args")`

### Terminal Setup

**`setup_terminal() -> Result<Terminal<CrosstermBackend<Stdout>>>`:**
1. `enable_raw_mode()` (crossterm)
2. `execute!(stdout, EnterAlternateScreen)` (crossterm)
3. Creates `Terminal::new(CrosstermBackend::new(stdout))`

**`restore_terminal(terminal: &mut Terminal<...>)`:**
1. `disable_raw_mode()`
2. `execute!(stdout, LeaveAlternateScreen)`
3. `terminal.show_cursor()`

### Relationship to TypeScript

`cc-tui` replaces the entire TypeScript `src/ink/` rendering system, `src/components/`, and React/Ink component tree. The ratatui approach is fundamentally different (immediate-mode rendering vs React reconciler), but provides equivalent visual functionality: message history, streaming text, input box, status bar, permission dialogs.

---

## Crate: `cc-commands`

**Path:** `crates/commands/src/lib.rs`

Slash command implementations for the interactive REPL.

### Core Types

**`CommandContext` struct:**
```
config: Config
cost_tracker: Arc<CostTracker>
messages: Vec<Message>
working_dir: PathBuf
```

**`CommandResult` enum:**
- `Message(String)` — display text to user
- `UserMessage(String)` — inject as user message into conversation
- `ConfigChange(Config)` — update running config
- `ClearConversation` — clear message history
- `SetMessages(Vec<Message>)` — replace message history
- `Exit` — terminate session
- `Silent` — no output
- `Error(String)` — display error

**`SlashCommand` trait** (async_trait):
- `fn name(&self) -> &str`
- `fn aliases(&self) -> Vec<&str>` (default: empty)
- `fn description(&self) -> &str`
- `fn help(&self) -> &str`
- `fn hidden(&self) -> bool` (default: false)
- `async fn execute(&self, args: &str, ctx: &CommandContext) -> CommandResult`

### Command Registry

**`all_commands() -> Vec<Box<dyn SlashCommand>>`** — returns all built-in commands

**`find_command(name: &str) -> Option<Box<dyn SlashCommand>>`** — matches by name or alias

**`execute_command(input: &str, ctx: &CommandContext) -> Option<CommandResult>`** (async):
- Parses slash command from input
- Finds matching command
- Returns `None` if no match (pass-through to query loop)

### Implemented Commands

| Struct | Name | Aliases | Description |
|---|---|---|---|
| `HelpCommand` | `help` | `h`, `?` | List available slash commands |
| `ClearCommand` | `clear` | `cls` | Clear conversation history |
| `CompactCommand` | `compact` | — | Manually compact conversation |
| `CostCommand` | `cost` | — | Show current session cost |
| `ExitCommand` | `exit` | `quit`, `q` | Exit the REPL |
| `ModelCommand` | `model` | — | Show/change current model |
| `ConfigCommand` | `config` | — | Show/update configuration |
| `VersionCommand` | `version` | — | Show version information |
| `ResumeCommand` | `resume` | — | Resume previous conversation |
| `StatusCommand` | `status` | — | Show session status |
| `DiffCommand` | `diff` | — | Show file diffs |
| `MemoryCommand` | `memory` | — | Manage CLAUDE.md memories |
| `BugCommand` | `bug` | — | File a bug report |
| `DoctorCommand` | `doctor` | — | Run diagnostics |
| `LoginCommand` | `login` | — | Authenticate |
| `LogoutCommand` | `logout` | — | Clear authentication |
| `InitCommand` | `init` | — | Initialize project CLAUDE.md |
| `ReviewCommand` | `review` | — | Code review workflow |
| `HooksCommand` | `hooks` | — | Manage event hooks |
| `McpCommand` | `mcp` | — | Manage MCP servers |
| `PermissionsCommand` | `permissions` | — | Show/edit permissions |
| `PlanCommand` | `plan` | — | Enter/exit plan mode |
| `TasksCommand` | `tasks` | — | View background tasks |
| `SessionCommand` | `session` | — | Session management |
| `ThinkingCommand` | `thinking` | — | Toggle extended thinking |
| `ExportCommand` | `export` | — | Export conversation |
| `SkillsCommand` | `skills` | — | List/manage skills |
| `RewindCommand` | `rewind` | — | Rewind conversation state |
| `StatsCommand` | `stats` | — | Show usage statistics |
| `FilesCommand` | `files` | — | List context files |
| `RenameCommand` | `rename` | — | Rename current session |
| `EffortCommand` | `effort` | — | Set effort/thinking level |
| `SummaryCommand` | `summary` | — | Summarize conversation |
| `CommitCommand` | `commit` | — | Run git commit workflow |

### Relationship to TypeScript

`cc-commands` corresponds to the TypeScript `src/commands/` directory (150+ files). Each TypeScript command module (e.g., `src/commands/compact/`, `src/commands/model/`) maps to a struct in this crate. The slash command names and behaviors are preserved.

---

## Crate: `cc-mcp`

**Path:** `crates/mcp/src/lib.rs`

Full MCP (Model Context Protocol) client implementation. Uses JSON-RPC 2.0 over stdio subprocess transport.

### JSON-RPC Types

**`JsonRpcRequest`:** `{ jsonrpc: "2.0", method: String, params: Option<Value>, id: Option<u64> }`
- `JsonRpcRequest::new(method, params, id)` — regular request
- `JsonRpcRequest::notification(method, params)` — no id

**`JsonRpcResponse`:** `{ jsonrpc: "2.0", id: Option<u64>, result: Option<Value>, error: Option<JsonRpcError> }`

**`JsonRpcError`:** `{ code: i32, message: String, data: Option<Value> }`

### MCP Protocol Types

**`InitializeParams`:** `{ protocol_version: "2024-11-05", capabilities: ClientCapabilities, client_info: ClientInfo }`

**`ClientCapabilities`:** `{ roots: Option<RootsCapability> }`

**`InitializeResult`:** `{ protocol_version: String, capabilities: ServerCapabilities, server_info: ServerInfo }`

**`ServerCapabilities`:** `{ tools: Option<ToolsCapability>, resources: Option<ResourcesCapability>, prompts: Option<PromptsCapability> }`

**`McpTool`:** `{ name: String, description: Option<String>, input_schema: Value }`
- `From<&McpTool> for ToolDefinition` — converts to cc-core ToolDefinition

**`CallToolParams`:** `{ name: String, arguments: Option<Value> }`

**`CallToolResult`:** `{ content: Vec<McpContent>, is_error: Option<bool> }`

**`McpContent` enum** (serde tagged):
- `Text { type: "text", text: String }`
- `Image { type: "image", data: String, mime_type: String }`
- `Resource { type: "resource", resource: ResourceContents }`

**`McpResource`:** `{ uri: String, name: String, description: Option<String>, mime_type: Option<String> }`

**`McpPrompt`:** `{ name: String, description: Option<String>, arguments: Option<Vec<McpPromptArgument>> }`

### Transport

**`McpTransport` trait** (async_trait):
- `async fn send(&mut self, request: &JsonRpcRequest) -> Result<()>`
- `async fn recv(&mut self) -> Result<Option<JsonRpcResponse>>`
- `async fn close(&mut self)`

**`StdioTransport`:**
- `StdioTransport::spawn(command: &str, args: &[String], env: &HashMap<String, String>) -> Result<Self>`
  - Spawns subprocess with piped stdin/stdout
  - Spawns background reader task forwarding lines to `mpsc::UnboundedReceiver<String>`
- `send()` — serializes to JSON + newline on stdin
- `recv()` — receives from channel, deserializes JSON-RPC response

### `McpClient`

**`McpClient::connect_stdio(config: &McpServerConfig) -> Result<Self>`** (async):
1. Calls `StdioTransport::spawn()`
2. Calls `initialize()` — sends `initialize` request, receives `InitializeResult`
3. Sends `notifications/initialized` notification
4. If `capabilities.tools` present: calls `tools/list`, stores in `self.tools`
5. If `capabilities.resources` present: calls `resources/list`, stores
6. If `capabilities.prompts` present: calls `prompts/list`, stores
7. Returns connected client

**`call<T: DeserializeOwned>(&mut self, method, params) -> Result<T>`:**
- Sequential request/response: sends request with incrementing ID
- Calls `transport.recv()` in loop until response ID matches
- Deserializes `result` field

**`call_tool(&mut self, name: &str, arguments: Option<Value>) -> Result<CallToolResult>`:**
- Calls `tools/call` with `CallToolParams`

**`list_resources(&mut self) -> Result<Vec<McpResource>>`** — `resources/list`

**`read_resource(&mut self, uri: &str) -> Result<ResourceContents>`** — `resources/read`

### `McpManager`

Manages multiple named MCP server connections.

**`McpManager::connect_all(configs: &[McpServerConfig]) -> Result<Self>`** (async):
- Attempts to connect each server; logs warnings on failure (doesn't abort)

**`all_tool_definitions(&self) -> Vec<ToolDefinition>`:**
- Prefixes each tool name with `"{server_name}_"` to namespace tools

**`call_tool(&self, prefixed_name: &str, arguments: Option<Value>) -> Result<CallToolResult>`:**
- Strips server prefix to identify server
- Routes to correct `McpClient`

**`list_all_resources(&self) -> Result<Vec<McpResource>>`:**
- Aggregates resources from all connected servers

**`read_resource(&self, uri: &str) -> Result<ResourceContents>`:**
- Tries each server until one returns a result

**`server_count(&self) -> usize`**, **`server_names(&self) -> Vec<String>`**

**`mcp_result_to_string(result: &CallToolResult) -> String`:**
- Converts `McpContent::Text` → text, `McpContent::Image` → `[image: mime_type]`, `McpContent::Resource` → URI/text

### Relationship to TypeScript

`cc-mcp` corresponds to `src/services/mcpClient.ts` (TypeScript MCP implementation). Implements the same MCP protocol version (`2024-11-05`), stdio transport, and tool namespacing convention.

---

## Crate: `cc-bridge`

**Path:** `crates/bridge/src/lib.rs`

Implements the bridge protocol connecting the local Claude Code CLI to the claude.ai web UI. Enables remote control of the CLI from a browser session.

### Configuration

**`BridgeConfig` struct:**
- `enabled: bool`
- `server_url: String`
- `device_id: String`
- `session_token: Option<String>`
- `polling_interval_ms: u64` (default: 1000)
- `max_reconnect_attempts: u32` (default: 10)

### Protocol Types

**`BridgeMessage` enum** (serde tagged — messages from server to client):
- `UserMessage { content: String, attachments: Vec<String> }`
- `PermissionResponse { tool_use_id: String, decision: PermissionDecision }`
- `Cancel`
- `Ping`

**`BridgeEvent` enum** (serde tagged — events from client to server):
- `TextDelta { text: String }`
- `ToolStart { tool_name: String, tool_id: String }`
- `ToolEnd { tool_name: String, tool_id: String, result: String, is_error: bool }`
- `PermissionRequest { tool_use_id: String, tool_name: String, description: String }`
- `TurnComplete { stop_reason: String }`
- `Error { message: String }`
- `Pong`

**`PermissionDecision` enum:** `Allow`, `AllowPermanently`, `Deny`, `DenyPermanently`

**`BridgeState` enum:** `Connecting`, `Connected`, `Reconnecting { attempt: u32 }`, `Disconnected`

### Session Management

**`BridgeSession::new(config: BridgeConfig) -> (Self, mpsc::Receiver<BridgeMessage>, mpsc::Sender<BridgeEvent>)`:**
- Creates channel pair for bidirectional communication

**`BridgeManager::start(config, msg_tx, event_rx) -> Self`:**
- Spawns `run_poll_loop()` background task
- Returns manager with `JoinHandle`

### Polling Loop

**`run_poll_loop(config, msg_tx, event_rx)`** (async):
1. Long-polls `{server_url}/sessions/{id}/poll` with `reqwest` GET
2. On response: deserializes `BridgeMessage` array, sends each to `msg_tx`
3. Drains `event_rx`: sends accumulated `BridgeEvent` items to `{server_url}/sessions/{id}/events` via POST
4. On network error: exponential backoff up to `max_reconnect_attempts`
5. On 401/403: sets state to `Disconnected`, exits loop

### Module: `jwt`

**`JwtClaims` struct:** `{ sub: String, exp: u64, iat: u64, device_id: String }`

**`decode_payload(token: &str) -> Result<JwtClaims>`:**
- Splits token by `"."`, takes index 1 (payload segment)
- Base64 decodes (URL-safe, no padding) via `base64` crate
- Deserializes JSON to `JwtClaims`

**`is_expired(claims: &JwtClaims) -> bool`:**
- Compares `claims.exp` against `SystemTime::now()` Unix timestamp

### Module: `trusted_device`

**`device_fingerprint() -> String`:**
- Collects: `hostname()` (from `hostname` crate), `USER` env var, home directory path
- SHA-256 hash of concatenated string via `sha2` crate
- Returns lowercase hex string (first 16 chars) via `hex` crate

### Relationship to TypeScript

`cc-bridge` corresponds to `src/bridge/` (31 TypeScript files including `bridgeMain.ts`, `bridgeMessaging.ts`, `replBridge.ts`, `jwtUtils.ts`, `trustedDevice.ts`, etc.). Implements the same polling-based bridge protocol and JWT handling.

---

## Crate: `claude-code` (CLI Binary)

**Path:** `crates/cli/src/main.rs`

Binary entry point. Produces the `claude` executable. Wires all crates together.

### CLI Arguments (`Cli` struct via clap derive)

| Flag | Type | Description |
|---|---|---|
| `prompt` | `Option<String>` (positional) | Non-interactive prompt |
| `-p, --print` | `bool` | Print mode (alias for non-interactive) |
| `-m, --model` | `Option<String>` | Override model |
| `--permission-mode` | `Option<CliPermissionMode>` | Permission mode |
| `--resume` | `Option<String>` | Resume session by ID |
| `--max-turns` | `u32` (default: 10) | Max conversation turns |
| `-s, --system-prompt` | `Option<String>` | Override system prompt |
| `--append-system-prompt` | `Option<String>` | Append to system prompt |
| `--no-claude-md` | `bool` | Skip CLAUDE.md loading |
| `--output-format` | `Option<CliOutputFormat>` | Output format |
| `-v, --verbose` | `bool` | Enable verbose logging |
| `--api-key` | `Option<String>` | API key |
| `--max-tokens` | `Option<u32>` | Override max tokens |
| `--cwd` | `Option<PathBuf>` | Working directory |
| `--dangerously-skip-permissions` | `bool` | BypassPermissions mode |
| `--dump-system-prompt` | `bool` | Print system prompt and exit |
| `--mcp-config` | `Option<PathBuf>` | MCP server config JSON file |
| `--no-auto-compact` | `bool` | Disable auto-compact |

**`CliPermissionMode` enum** (clap ValueEnum): `Default`, `AcceptEdits`, `BypassPermissions`, `Plan`

**`CliOutputFormat` enum** (clap ValueEnum): `Text`, `Json`, `StreamJson`

### `McpToolWrapper`

Implements `Tool` for tools provided by MCP servers:
- `permission_level()` → `Execute`
- `execute()` strips server prefix from tool name, calls `McpManager::call_tool()`, converts result via `mcp_result_to_string()`

### `main()` Function

1. Parses `Cli` args with clap
2. Sets up `tracing_subscriber` (verbose → DEBUG, default → WARN)
3. Loads `Settings` from `~/.claude/settings.json`
4. Builds `Config` by layering: settings → CLI overrides
5. Determines `working_dir` (from `--cwd` or `std::env::current_dir()`)
6. Creates `Arc<CostTracker>`
7. Builds system context strings:
   - Reads `crates/cli/src/system_prompt.txt` (embedded at compile time via `include_str!`)
   - Calls `ContextBuilder::build_system_context()`
   - Calls `ContextBuilder::build_user_context()` (unless `--no-claude-md`)
   - Joins all parts
8. If `--dump-system-prompt`: prints and exits
9. Creates `AnthropicClient::from_config()`
10. Creates `ToolContext` with `AutoPermissionHandler`
11. Calls `McpManager::connect_all()` if MCP config provided
12. Builds tool list: `cc_tools::all_tools()` + `AgentTool` + `McpToolWrapper` for each MCP tool
13. Creates `CancellationToken`, starts cron scheduler with `start_cron_scheduler()`
14. If prompt provided or `--print`: calls `run_headless()`
15. Otherwise: calls `run_interactive()`

### `run_headless(prompt, client, messages, tools, tool_ctx, config, cost_tracker, output_format)`

1. Reads prompt from arg or stdin (if no positional arg)
2. Pushes `Message::user(prompt)` to messages
3. Spawns `run_query_loop()` with `mpsc::unbounded_channel()` for events
4. Drains event channel:
   - `Text` output format: prints `QueryEvent::Stream(TextDelta)` text directly; prints tool names
   - `Json` format: collects full response, outputs as single JSON object
   - `StreamJson` format: outputs each `QueryEvent` as NDJSON line
5. Returns on `QueryOutcome::EndTurn` or error

### `run_interactive()`

Interactive TUI REPL:
1. Sets up terminal via `cc_tui::setup_terminal()`
2. Restores terminal on exit (via `defer`-pattern)
3. Handles session resume if `--resume` provided
4. Main event loop at 16ms poll interval (`EventStream` from crossterm):
   - Processes `crossterm::event::KeyEvent` via `app.handle_key_event()`
   - On Enter: if slash command (`is_slash_command()`), calls `execute_command()` from `cc-commands`
   - Regular message: pushes to `messages`, spawns `run_query_loop()` as `tokio::spawn`
   - Shares `Arc<Mutex<Vec<Message>>>` between main and spawned task for result sync
   - Drains query events via `event_rx.try_recv()`
   - Calls `app.handle_query_event()` to update TUI state
   - Re-renders via `terminal.draw(|f| render_app(f, &app))`
5. Saves session to `cc_core::history::save_session()` after each completed turn

### System Prompt (`system_prompt.txt`)

Embedded in binary at compile time. Content:
> You are Claude Code, an AI coding assistant by Anthropic.

Guidelines:
- Read files before editing them
- Prefer editing existing files over creating new ones
- Write clean, idiomatic code
- Run tests after making changes
- Use git log/diff for codebase context
- Be concise in responses
- Produce production-quality code
- Never introduce security vulnerabilities

### Relationship to TypeScript

`claude-code` CLI corresponds to `src/entrypoints/cli.tsx` (the main TypeScript CLI entry point), `src/main.tsx`, `src/screens/REPL.tsx`, and `src/cli/` directory. The CLI flag names and behaviors are preserved, including `--print`, `--output-format`, `--permission-mode`, and `--resume`.

---

## Cross-Cutting Architecture Notes

### Async Runtime
All async code uses `tokio` with `"full"` features. The `#[tokio::main]` macro is on `main()` in `crates/cli/src/main.rs`. All tools use `async fn execute()` via `async_trait`.

### Cancellation
`tokio_util::sync::CancellationToken` is threaded through `run_query_loop()`, the cron scheduler, and TUI event loop. `Ctrl+C` fires the token.

### Global State
Three `DashMap`/`RwLock` singletons using `once_cell::sync::Lazy`:
- `TASK_STORE` (cc-tools/tasks.rs) — task management
- `INBOX` (cc-tools/send_message.rs) — inter-agent messaging
- `CRON_STORE` (cc-tools/cron.rs) — scheduled tasks
- `WORKTREE_SESSION` (cc-tools/worktree.rs) — active git worktree

### Error Handling
- Libraries use `thiserror` for typed `ClaudeError`
- CLI binary uses `anyhow` for ergonomic error propagation
- Tool errors never panic; always return `ToolResult::error()`

### Prompt Caching
`cc-api` automatically applies `CacheControl::ephemeral()` to:
- System prompt blocks (when using `SystemPrompt::Blocks`)
- The last tool definition in the tools list

### Logging
`tracing` + `tracing-subscriber` with `EnvFilter`. Default level WARN; `--verbose` enables DEBUG. Structured fields on all log calls.

### TypeScript Parity Summary

| TypeScript Area | Rust Crate |
|---|---|
| `src/entrypoints/cli.tsx`, `src/main.tsx` | `crates/cli` |
| `src/services/api/` | `crates/api` |
| `src/query.ts`, `src/query/` | `crates/query` |
| `src/components/`, `src/ink/` | `crates/tui` |
| `src/commands/` | `crates/commands` |
| `src/constants/`, `src/context.ts`, etc. | `crates/core` |
| Tool implementations (Bash, Read, Edit, etc.) | `crates/tools` |
| MCP client (`src/services/mcpClient.ts`) | `crates/mcp` |
| `src/bridge/` | `crates/bridge` |