> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/yocxy2/claurst/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How Claurst is structured: workspace crates, dependency flow, the agentic query loop, and the TUI layer.

Claurst is a **complete standalone rewrite** of the Claude Code CLI in async Rust. It shares no runtime code with the original TypeScript implementation and re-implements the same tool names, permission model, CLAUDE.md discovery, auto-compact logic, MCP client, and bridge protocol — all in idiomatic Rust on the Tokio async runtime.

## Workspace structure

The workspace lives under `claude-code-rust/` and is organized as a Cargo workspace with `resolver = "2"`, edition `2021`.

```
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 (produces `claude` executable)
```

| Package       | Type    | Purpose                                                                      |
| ------------- | ------- | ---------------------------------------------------------------------------- |
| `cc-core`     | Library | Shared types, error enum, config, permissions, history, cost tracking, hooks |
| `cc-api`      | Library | Anthropic Messages API client with SSE streaming and retry logic             |
| `cc-tools`    | Library | All 33 built-in tool implementations                                         |
| `cc-query`    | Library | Agentic query loop, auto-compact, sub-agent tool, cron scheduler             |
| `cc-tui`      | Library | Terminal UI (ratatui + crossterm)                                            |
| `cc-commands` | Library | Slash command registry and implementations                                   |
| `cc-mcp`      | Library | JSON-RPC 2.0 MCP client over stdio subprocess transport                      |
| `cc-bridge`   | Library | Bridge protocol for claude.ai remote control                                 |
| `claude-code` | Binary  | CLI entry point; binary named `claude`                                       |

## Dependency flow

```
cli → query → tools → core
         ↓         ↗
        api  →  core
         ↓
       commands → core
         ↓
        tui   → core
         ↓
        mcp   → core
         ↓
       bridge → core
```

`cc-core` is the only crate with no upstream dependencies within the workspace. Every other crate depends on it for shared types, error handling, and configuration. The CLI binary wires everything together.

## Agentic query loop

The core of Claurst is the agentic loop implemented in `cc-query`. A single user turn follows this flow:

<Steps>
  <Step title="Receive user input">
    The TUI or headless runner receives a user prompt and appends it to the in-process message history as a `Message::user(...)`.
  </Step>

  <Step title="Build the API request">
    `run_query_loop()` converts the message history to `Vec<ApiMessage>`, converts available tools to `Vec<ApiToolDefinition>`, and assembles a `CreateMessageRequest` with the system prompt and optional thinking budget.
  </Step>

  <Step title="Stream the response">
    `AnthropicClient::create_message_stream()` spawns a background Tokio task that reads the SSE response body line by line and sends `StreamEvent` values over an `mpsc` channel (buffer: 256). A `StreamAccumulator` collects deltas into a complete `Message`.
  </Step>

  <Step title="Execute tools">
    When `stop_reason` is `tool_use`, the loop iterates over every `ContentBlock::ToolUse` in the response. For each block it fires `PreToolUse` hooks, calls `execute_tool()`, fires `PostToolUse` hooks, and collects `ToolResult` values into a `Message::user_blocks(result_blocks)` appended to the history.
  </Step>

  <Step title="Loop or return">
    If tool results were appended, the loop continues from step 2. The loop terminates when `stop_reason` is `end_turn` or `stop_sequence` (returns `QueryOutcome::EndTurn`), `max_tokens` (returns `QueryOutcome::MaxTokens`), the turn counter exceeds `max_turns` (default: 10), or the `CancellationToken` fires.
  </Step>
</Steps>

Auto-compact runs between turns. When token usage exceeds 90% of the model's context window, the loop summarises the head of the conversation and replaces it with a `<compact-summary>` block, keeping the last 10 messages intact.

## TUI layer

`cc-tui` replaces the TypeScript Ink/React rendering layer with an immediate-mode terminal UI:

* **Backend:** `ratatui` + `crossterm`. The terminal is placed in raw mode with `crossterm::terminal::enable_raw_mode()` and switched to the alternate screen buffer.
* **Layout:** Three vertical chunks — messages area (flex fill), input box (3 rows), status bar (1 row).
* **Rendering:** User messages render in Cyan, assistant messages in Green. Streaming text in progress renders in Yellow italic. The status bar shows the active model and current session cost.
* **Input:** `App::handle_key_event()` processes `KeyEvent` values. `Ctrl+C` cancels a streaming response; if the input is empty it quits. Up/Down navigates input history. `F1` or `?` toggles the help overlay.
* **Widgets:** A centered `render_permission_dialog()` popup handles user permission prompts. A braille spinner (`⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`) animates during tool execution.

For headless (non-interactive) use, `run_headless()` streams `QueryEvent` values to stdout in `text`, `json`, or `stream-json` output formats without starting the TUI.

## Async runtime

All async code uses **Tokio** with the `full` feature set. The `#[tokio::main]` macro is applied to `main()` in `crates/cli/src/main.rs`. Every tool's `execute()` method is `async` via `async_trait`. Cancellation is propagated through `tokio_util::sync::CancellationToken`.

## Key shared dependencies

| Crate                  | Version | Role                                   |
| ---------------------- | ------- | -------------------------------------- |
| `tokio`                | 1.44    | Async runtime (`full` features)        |
| `reqwest`              | 0.12    | HTTP client (rustls-tls, streaming)    |
| `ratatui`              | 0.29    | Terminal UI framework                  |
| `crossterm`            | 0.28    | Cross-platform terminal backend        |
| `clap`                 | 4       | CLI argument parsing                   |
| `serde` / `serde_json` | 1       | Serialization                          |
| `schemars`             | 0.8     | JSON Schema generation for tool inputs |
| `async-trait`          | 0.1     | Async trait support                    |
| `dashmap`              | 6       | Concurrent hash maps for global state  |
| `parking_lot`          | 0.12    | Faster mutexes                         |

***

<CardGroup cols={2}>
  <Card title="Tool system" icon="wrench" href="/concepts/tool-system">
    How the Tool trait works, the 33 built-in tools, and input schema validation.
  </Card>

  <Card title="Permissions" icon="shield" href="/concepts/permissions">
    Permission modes, categories, layered settings, and protected files.
  </Card>

  <Card title="Memory" icon="brain" href="/concepts/memory">
    Short-term session history, the memdir long-term store, and the AutoDream consolidation system.
  </Card>

  <Card title="Back to overview" icon="house" href="/">
    Return to the documentation home.
  </Card>
</CardGroup>