claw-code/docs/ARCHITECTURE.md

claw-code Architecture

A high-level overview of how claw-code is structured. For implementation details, see source code in rust/crates/. For provider details, see SUPPORTED_PROVIDERS.md. For pinpoint navigation, see ROADMAP.md.

Overview

claw-code is a Rust-based CLI for interacting with LLM providers (Anthropic, OpenAI-compatible, xAI, DashScope, etc.). It provides:

• Streaming conversation with auto-compaction
• Tool execution (file read/write, bash, MCP)
• Multi-provider routing
• Session persistence
• Parallel agent execution

Workspace Layout

The Rust workspace is organized in rust/crates/:

Core crates

• rusty-claude-cli — CLI entry point. Parses args, routes commands, manages TUI/headless modes.
• runtime — Conversation engine. Manages session state, message history, auto-compaction, tool dispatch, hooks, MCP, and branch/lane events.
• api — Provider abstraction. Hosts MODEL_REGISTRY (provider/model routing), SSE streaming, request/response handling. Providers: anthropic, openai_compat.
• tools — Tool definitions. File I/O, bash execution, MCP integration, PDF extraction.

Support crates

• commands — Parsed command dispatch layer between CLI and runtime.
• plugins — Plugin/hook lifecycle (hooks.rs).
• telemetry — Metrics and tracing instrumentation.
• compat-harness — Parity test harness for Rust-port validation.
• mock-anthropic-service — Local mock server for offline/test use.

Request Flow

1. CLI parse (rusty-claude-cli/src/main.rs) — interprets args, env vars, settings.json
2. Provider selection (api/src/providers/mod.rs) — routes to provider via MODEL_REGISTRY based on model prefix
3. Conversation execution (runtime/src/conversation.rs) — sends to provider via SSE, receives streamed response
4. Tool dispatch (tools/src/lib.rs) — if response includes tool_use, execute and feed back tool_result
5. Auto-compaction check (runtime/src/compact.rs) — REACTIVE-AFTER-SUCCESS only (see #287 for preflight gap)
6. Output — JSON envelope (--output-format json) or text (default)

Key Subsystems

Auto-compaction

Triggered post-turn when usage.input_tokens > threshold. See:

• Threshold via env-only (#283)
• Reactive-not-preflight (#287, CRITICAL)
• Manual /compact skip-reasons (#289)
• Failure envelope coverage (#288)

Provider routing

Hard-coded MODEL_REGISTRY + env-var-based auth + model-prefix heuristics. See:

• SUPPORTED_PROVIDERS.md for current providers
• #285 for declarative providers/models/websearch source-of-truth
• #245, #246 for declarative config & backend swap
• #290, #291, #292 for transport resilience (stream-init, circuit-breaker, escalation)

Parallel agents

Lane-based execution via runtime/src/lane_events.rs. Manifest-driven lifecycle. See:

• #286 for detached-thread + no-heartbeat issue (CRITICAL)

Tool lifecycle / hooks

Tools defined in tools/src/. Hook events emitted via runtime/src/hooks.rs and plugins/src/hooks.rs. See:

• #254 (MCP refresh)
• #268 (tool-rendering parity)
• #274 (hook-execution-event envelope)
• #280 (hook event tap)

Session persistence

Sessions managed in runtime/src/session.rs. See:

• #278 (version-comparison)
• #279 (unknown-field policy)

CLI dispatch

CLI parsing in rusty-claude-cli/src/main.rs. Issues:

• #262 --max-turns spec
• #267 --cwd runtime fix
• #272 position-independent parsing
• #282 env-vs-config consolidation

Build & Test

See CONTRIBUTING.md for build commands. Quick reference:

cd rust && cargo build        # Build all crates
cd rust && cargo test         # Run all Rust tests

Tracing & Debugging

• Session state: runtime/src/session.rs + ~/.claw/sessions/<id>/
• Provider responses: Set RUST_LOG=trace for verbose SSE logs
• Parity checks: Use compat-harness crate for Rust-port validation

Related Documents

• ROADMAP.md — Pinpoints by cluster
• TROUBLESHOOTING.md — User-facing failure mitigation
• SUPPORTED_PROVIDERS.md — Provider/model details
• CONTRIBUTING.md — Pinpoint filing format
• PINPOINT_FILING_GUIDE.md — Filing workflow
• CHANGELOG.md — Recent changes