# ultraworkers/claw-code architecture

> Architecture diagram of the GitHub repository ultraworkers/claw-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ultraworkers/claw-code
- Repository: https://github.com/ultraworkers/claw-code
- Video tour (about a minute): https://gitdiagram.com/ultraworkers/claw-code/video

## Overview

Claw Code is the canonical Rust implementation of the `claw` CLI agent harness; the Python tree is described as a companion/reference workspace, not the primary runtime. The documented user path is to launch the CLI, run `doctor` to check setup, then submit a prompt or start an interactive session. The graph includes provider routing and the separate RAG indexing capability visible in the source index. Several Rust runtime subsystems are unsampled, so their relationships are shown only as unverified links or omitted.

Main entry points: [`rust/crates/runtime/src/worker_boot.rs`](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/runtime/src/worker_boot.rs) (Worker boot), [`rust/crates/claw-rag-service/src/ingest.rs`](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/ingest.rs) (Workspace ingestion), [`rust/crates/api/src/client.rs`](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/client.rs) (Provider client), [`rust/crates/rusty-claude-cli/src/main.rs`](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/rusty-claude-cli/src/main.rs) (Claw CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and setup"]
  node_cli["Claw CLI<br/>[main.rs]"]
  node_doctor["Health checks<br/>[doctor.rs]"]
  node_config["Configuration<br/>[config.rs]"]
end

subgraph group_agent["Agent runtime"]
  node_commands["Command handling<br/>[lib.rs]"]
  node_session["Session control<br/>[session_control.rs]"]
  node_worker["Worker boot<br/>[worker_boot.rs]"]
  node_policy["Policy enforcement<br/>[policy_engine.rs]"]
  node_tools["Tool execution<br/>[lib.rs]"]
  node_plugins["Plugin lifecycle<br/>[lib.rs]"]
end

subgraph group_models["Model API"]
  node_api["Provider client<br/>[client.rs]"]
  node_anthropic["Anthropic provider<br/>[anthropic.rs]"]
  node_openai["OpenAI-compatible<br/>[openai_compat.rs]"]
  node_http["HTTP transport<br/>[http_client.rs]"]
  node_cache["Prompt cache<br/>[prompt_cache.rs]"]
end

subgraph group_knowledge["Knowledge indexing"]
  node_ingest["Workspace ingestion<br/>[ingest.rs]"]
  node_chunk["Text chunking<br/>[chunk.rs]"]
  node_embedding["Embedding service<br/>[embed.rs]"]
  node_index["Vector index<br/>[qdrant_index.rs]"]
  node_database[("SQLite store<br/>[db.rs]")]
end

node_user(("CLI user"))
node_modelservice(("Model API service"))

node_user -->|"runs"| node_cli
node_cli -->|"runs health check"| node_doctor
node_user -->|"submits prompt"| node_cli
node_cli -.->|"starts session"| node_session
node_session -.->|"starts worker"| node_worker
node_worker -.->|"dispatches commands"| node_commands
node_worker -.->|"checks policy"| node_policy
node_worker -.->|"invokes tools"| node_tools
node_worker -.->|"requests completion"| node_api
node_worker -.->|"runs plugins"| node_plugins
node_api -->|"routes requests"| node_anthropic
node_api -->|"routes requests"| node_openai
node_api -->|"configures cache"| node_cache
node_anthropic -->|"uses transport"| node_http
node_openai -->|"uses transport"| node_http
node_anthropic -.->|"sends requests"| node_modelservice
node_openai -.->|"sends requests"| node_modelservice
node_ingest -->|"chunks files"| node_chunk
node_ingest -->|"embeds batches"| node_embedding
node_ingest -->|"writes records"| node_database
node_ingest -->|"updates index"| node_index

click node_cli "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/rusty-claude-cli/src/main.rs"
click node_doctor "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-analog/src/doctor.rs"
click node_config "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/runtime/src/config.rs"
click node_commands "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/commands/src/lib.rs"
click node_session "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/runtime/src/session_control.rs"
click node_worker "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/runtime/src/worker_boot.rs"
click node_policy "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/runtime/src/policy_engine.rs"
click node_tools "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/tools/src/lib.rs"
click node_plugins "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/plugins/src/lib.rs"
click node_api "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/client.rs"
click node_anthropic "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/providers/anthropic.rs"
click node_openai "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/providers/openai_compat.rs"
click node_http "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/http_client.rs"
click node_cache "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/prompt_cache.rs"
click node_ingest "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/ingest.rs"
click node_chunk "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/chunk.rs"
click node_embedding "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/embed.rs"
click node_index "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/qdrant_index.rs"
click node_database "https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/db.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_doctor,node_config,node_user toneBlue
class node_commands,node_session,node_worker,node_policy,node_tools,node_plugins toneAmber
class node_api,node_anthropic,node_openai,node_http,node_cache,node_modelservice toneMint
class node_ingest,node_chunk,node_embedding,node_index,node_database toneRose
```

## Components

### CLI and setup

- [Claw CLI](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/rusty-claude-cli/src/main.rs): `rust/crates/rusty-claude-cli/src/main.rs`
- [Health checks](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-analog/src/doctor.rs): `rust/crates/claw-analog/src/doctor.rs`
- [Configuration](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/runtime/src/config.rs): `rust/crates/runtime/src/config.rs`

### Agent runtime

- [Command handling](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/commands/src/lib.rs): `rust/crates/commands/src/lib.rs`
- [Session control](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/runtime/src/session_control.rs): `rust/crates/runtime/src/session_control.rs`
- [Worker boot](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/runtime/src/worker_boot.rs): `rust/crates/runtime/src/worker_boot.rs`
- [Policy enforcement](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/runtime/src/policy_engine.rs): `rust/crates/runtime/src/policy_engine.rs`
- [Tool execution](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/tools/src/lib.rs): `rust/crates/tools/src/lib.rs`
- [Plugin lifecycle](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/plugins/src/lib.rs): `rust/crates/plugins/src/lib.rs`

### Model API

- [Provider client](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/client.rs): `rust/crates/api/src/client.rs`
- [Anthropic provider](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/providers/anthropic.rs): `rust/crates/api/src/providers/anthropic.rs`
- [OpenAI-compatible](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/providers/openai_compat.rs): `rust/crates/api/src/providers/openai_compat.rs`
- [HTTP transport](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/http_client.rs): `rust/crates/api/src/http_client.rs`
- [Prompt cache](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/api/src/prompt_cache.rs): `rust/crates/api/src/prompt_cache.rs`

### Knowledge indexing

- [Workspace ingestion](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/ingest.rs): `rust/crates/claw-rag-service/src/ingest.rs`
- [Text chunking](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/chunk.rs): `rust/crates/claw-rag-service/src/chunk.rs`
- [Embedding service](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/embed.rs): `rust/crates/claw-rag-service/src/embed.rs`
- [Vector index](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/qdrant_index.rs): `rust/crates/claw-rag-service/src/qdrant_index.rs`
- [SQLite store](https://github.com/ultraworkers/claw-code/blob/main/rust/crates/claw-rag-service/src/db.rs): `rust/crates/claw-rag-service/src/db.rs`

### Other components

- **CLI user**
- **Model API service**

## Connections

- CLI user → Claw CLI: runs (evidence: `README.md`)
- Claw CLI → Health checks: runs health check (evidence: `README.md`)
- CLI user → Claw CLI: submits prompt (evidence: `README.md`)
- Claw CLI → Session control: starts session
- Session control → Worker boot: starts worker
- Worker boot → Command handling: dispatches commands
- Worker boot → Policy enforcement: checks policy
- Worker boot → Tool execution: invokes tools
- Worker boot → Provider client: requests completion
- Worker boot → Plugin lifecycle: runs plugins
- Provider client → Anthropic provider: routes requests (evidence: `rust/crates/api/src/client.rs`)
- Provider client → OpenAI-compatible: routes requests (evidence: `rust/crates/api/src/client.rs`)
- Provider client → Prompt cache: configures cache (evidence: `rust/crates/api/src/client.rs`)
- Anthropic provider → HTTP transport: uses transport (evidence: `rust/crates/api/src/providers/anthropic.rs`)
- OpenAI-compatible → HTTP transport: uses transport (evidence: `rust/crates/api/src/providers/openai_compat.rs`)
- Anthropic provider → Model API service: sends requests
- OpenAI-compatible → Model API service: sends requests
- Workspace ingestion → Text chunking: chunks files (evidence: `rust/crates/claw-rag-service/src/ingest.rs`)
- Workspace ingestion → Embedding service: embeds batches (evidence: `rust/crates/claw-rag-service/src/ingest.rs`)
- Workspace ingestion → SQLite store: writes records (evidence: `rust/crates/claw-rag-service/src/ingest.rs`)
- Workspace ingestion → Vector index: updates index (evidence: `rust/crates/claw-rag-service/src/ingest.rs`)
