# selvin-paul-raj/claw-code architecture

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

- Interactive diagram: https://gitdiagram.com/selvin-paul-raj/claw-code
- Repository: https://github.com/selvin-paul-raj/claw-code

## Overview

1. **Overall shape**
   - This repo is a dual-language project, but the **Rust workspace under `rust/` is the canonical product surface**: it builds the `claw` CLI agent harness.
   - The top-level `src/` tree is a **Python/reference workspace** used for parity auditing, subsystem snapshots, and migration helpers; it is not the primary runtime.

2. **Primary runtime boundary**
   - The Rust workspace is organized as a set of crates that separate:
     - the **CLI shell**,
     - the **agent/runtime orchestration layer**,
     - the **API/provider layer**,
     - and supporting subsystems like plugins, telemetry, tools, and mocks.
   - This gives a clean boundary between user-facing commands, execution policy, and external model/provider communication.

3. **CLI entrypoint**
   - `rust/crates/rusty-claude-cli` is the executable front door.
   - It handles command-line parsing, interactive input/rendering, and startup behavior, then delegates into the runtime and command crates.
   - The top-level README points users to `claw doctor`, `login`, `prompt`, and session workflows, so the CLI is the main user interaction layer.

4. **Runtime orchestration layer**
   - `rust/crates/runtime` is the core control plane for agent execution.
   - It contains modules for configuration, session state, prompts, permissions, sandboxing, hooks, MCP integration, git/worktree context, branch/session control, and recovery/summary logic.
   - This crate is the main boundary where input from the CLI becomes an orchestrated agent session with policy, filesystem, and process control.

5. **Model/API boundary**
   - `rust/crates/api` isolates all provider-facing concerns.
   - It includes HTTP client behavior, streaming/SSE handling, prompt caching, error types, and provider adapters for Anthropic and OpenAI-compatible endpoints.
   - Architecture-wise, this is the only layer that should know how to talk to remote model APIs; the runtime consumes it rather than embedding provider details directly.

6. **Tools and capability execution**
   - `rust/crates/tools` contains reusable operational tools such as lane completion and PDF extraction.
   - These are not the agent itself; they are capability modules that the runtime can invoke through its tool/task plumbing.
   - In the broader architecture, tools sit between agent intent and concrete side effects.

7. **Plugin and hook system**
   - `rust/crates/plugins` plus bundled examples define the plugin model and hook conventions.
   - The runtime also has hook, lifecycle, and permission enforcement modules, which indicates that plugins are executed through a constrained lifecycle rather than directly.
   - This creates a clear extension boundary: plugins can augment behavior, but the runtime still controls execution, trust, and policy.

8. **MCP and remote integration**
   - The runtime contains multiple MCP-related modules (`mcp`, `mcp_client`, `mcp_server`, `mcp_stdio`, `mcp_tool_bridge`, lifecycle hardening).
   - That suggests the agent can expose or consume tools over the Model Context Protocol and bridge those into the internal tool system.
   - This is a key integration boundary: internal task execution can be extended by remote or external tool servers.

9. **Auth, trust, permissions, and sandboxing**
   - The runtime includes OAuth, trust resolution, permission enforcement, policy engine, sandboxing, and branch-locking modules.
   - These form the safety boundary around agent actions: before a task can mutate files, invoke commands, or access resources, the runtime decides whether it is allowed and under what constraints.
   - If you are drawing the architecture, this should be shown as a governance layer wrapping execution.

10. **Session, conversation, and persistence**
   - The runtime has dedicated modules for sessions, conversation management, transcripts, history, task registry, task packets, usage, and summary compression.
   - This indicates the system preserves state across interactive turns and likely serializes session data for resume/recovery workflows.
   - The CLI consumes this state to support session resumption and compacted histories.

11. **Testing, parity, and mock infrastructure**
   - The repo invests heavily in parity validation: `rust/compat-harness`, `rust/mock-anthropic-service`, `rust/mock_parity_scenarios.json`, and the parity-harness scripts.
   - This is reinforced by the top-level Python helpers such as `src/parity_audit.py`, `src/reference_data/`, and `tests/test_porting_workspace.py`.
   - Architecturally, there is a deliberate split between the production runtime and a deterministic test/migration harness used to compare behavior against reference implementations.

12. **Repository operations and delivery**
   - CI is Rust-focused (`.github/workflows/rust-ci.yml`) with a release pipeline and a doc/source-of-truth checker.
   - Container support is first-class via `Containerfile` and `docs/container.md`, which suggests reproducible builds and containerized workflows are part of the deployment story.
   - `install.sh`, `USAGE.md`, and `rust/README.md` are operational docs rather than code, but they describe the intended lifecycle: build, authenticate, run, test, and validate parity.

13. **How to read the architecture at a glance**
   - Data flow is: **user command in CLI → runtime orchestration → policy/sandbox/session layers → API/provider or tool/MCP execution → streamed output back to CLI**.
   - Side channels include **plugins/hooks**, **git/worktree context**, and **telemetry/usage**.
   - The Python tree and mock harnesses exist primarily to **audit, compare, and preserve behavior during the Rust port** rather than to power the main runtime.

Main entry points: [`rust/crates/runtime/src/lib.rs`](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/lib.rs) (Runtime core), [`rust/crates/compat-harness/src/lib.rs`](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/compat-harness/src/lib.rs) (Parity harness), [`rust/crates/rusty-claude-cli/src/main.rs`](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/rusty-claude-cli/src/main.rs) (CLI shell), [`rust/crates/api/src/lib.rs`](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/api/src/lib.rs) (Provider API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rust["Rust product"]
  node_cli["CLI shell<br/>binary entrypoint<br/>[main.rs]"]
  node_cli_input["Input<br/>cli interaction<br/>[input.rs]"]
  node_cli_render["Render<br/>cli output<br/>[render.rs]"]
  node_cli_init["Startup<br/>cli bootstrap<br/>[init.rs]"]
  node_runtime{{"Runtime core<br/>agent control plane<br/>[lib.rs]"}}
  node_runtime_session["Sessions<br/>state and persistence<br/>[session.rs]"]
  node_runtime_policy["Policy<br/>governance layer<br/>[policy_engine.rs]"]
  node_runtime_integration["Integrations<br/>external bridge<br/>[mcp.rs]"]
  node_runtime_context["Context<br/>[git_context.rs]"]
  node_api{{"Provider API<br/>model boundary<br/>[lib.rs]"}}
  node_api_providers["Providers<br/>adapter layer<br/>[mod.rs]"]
  node_api_transport["Transport<br/>http/sse plumbing<br/>[http_client.rs]"]
  node_tools["Tools<br/>capability modules<br/>[lib.rs]"]
  node_plugins["Plugins<br/>extension system<br/>[lib.rs]"]
  node_telemetry["Telemetry<br/>usage reporting<br/>[lib.rs]"]
end

subgraph group_python["Python reference"]
  node_python_ref["Python tree<br/>reference workspace<br/>[main.py]"]
  node_parity_audit["Parity audit<br/>comparison tooling<br/>[parity_audit.py]"]
end

subgraph group_ops["Validation and delivery"]
  node_compat["Parity harness<br/>test harness<br/>[lib.rs]"]
  node_ops_ci["CI & release<br/>delivery pipeline<br/>[rust-ci.yml]"]
end

node_cli -->|"parse"| node_cli_input
node_cli -->|"render"| node_cli_render
node_cli -->|"bootstrap"| node_cli_init
node_cli -->|"delegate"| node_runtime
node_runtime -->|"manage"| node_runtime_session
node_runtime -->|"enforce"| node_runtime_policy
node_runtime -->|"bridge"| node_runtime_integration
node_runtime -->|"context"| node_runtime_context
node_runtime -->|"call"| node_api
node_runtime -->|"invoke"| node_tools
node_runtime -->|"emit"| node_telemetry
node_api -->|"transport"| node_api_transport
node_api -->|"adapt"| node_api_providers
node_runtime_integration -->|"load"| node_plugins
node_runtime_integration -->|"exercise"| node_compat
node_python_ref -->|"audit"| node_parity_audit
node_compat -.->|"mock"| node_api
node_compat -.->|"compare"| node_runtime
node_parity_audit -.->|"check"| node_compat
node_ops_ci -->|"validate"| node_compat
node_ops_ci -->|"verify"| node_python_ref

click node_cli "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/rusty-claude-cli/src/main.rs"
click node_cli_input "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/rusty-claude-cli/src/input.rs"
click node_cli_render "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/rusty-claude-cli/src/render.rs"
click node_cli_init "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/rusty-claude-cli/src/init.rs"
click node_runtime "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/lib.rs"
click node_runtime_session "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/session.rs"
click node_runtime_policy "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/policy_engine.rs"
click node_runtime_integration "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/mcp.rs"
click node_runtime_context "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/git_context.rs"
click node_api "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/api/src/lib.rs"
click node_api_providers "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/api/src/providers/mod.rs"
click node_api_transport "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/api/src/http_client.rs"
click node_tools "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/tools/src/lib.rs"
click node_plugins "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/plugins/src/lib.rs"
click node_telemetry "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/telemetry/src/lib.rs"
click node_compat "https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/compat-harness/src/lib.rs"
click node_python_ref "https://github.com/selvin-paul-raj/claw-code/blob/main/src/main.py"
click node_parity_audit "https://github.com/selvin-paul-raj/claw-code/blob/main/src/parity_audit.py"
click node_ops_ci "https://github.com/selvin-paul-raj/claw-code/blob/main/.github/workflows/rust-ci.yml"

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_cli_input,node_cli_render,node_cli_init,node_runtime,node_runtime_session,node_runtime_policy,node_runtime_integration,node_runtime_context,node_api,node_api_providers,node_api_transport,node_tools,node_plugins,node_telemetry toneBlue
class node_python_ref,node_parity_audit toneAmber
class node_compat,node_ops_ci toneMint
```

## Components

### Rust product

Primary CLI agent runtime and supporting crates under rust/

- [CLI shell](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/rusty-claude-cli/src/main.rs): binary entrypoint · Executable front door for commands, prompts, interactive input, and output rendering. · `rust/crates/rusty-claude-cli/src/main.rs`
- [Input](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/rusty-claude-cli/src/input.rs): cli interaction · Command parsing and interactive input handling. · `rust/crates/rusty-claude-cli/src/input.rs`
- [Render](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/rusty-claude-cli/src/render.rs): cli output · Terminal rendering and presentation of streamed responses and status. · `rust/crates/rusty-claude-cli/src/render.rs`
- [Startup](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/rusty-claude-cli/src/init.rs): cli bootstrap · Initial CLI setup, defaults, and startup behavior before delegating to runtime. · `rust/crates/rusty-claude-cli/src/init.rs`
- [Runtime core](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/lib.rs): agent control plane · Session orchestration, policy, filesystem/process control, and agent execution boundaries. · `rust/crates/runtime/src/lib.rs`
- [Sessions](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/session.rs): state and persistence · Conversation state, task registry, transcripts, summaries, and resume/recovery flows. · `rust/crates/runtime/src/session.rs`
- [Policy](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/policy_engine.rs): governance layer · Permissions, trust resolution, policy enforcement, sandboxing, and branch locking. · `rust/crates/runtime/src/policy_engine.rs`
- [Integrations](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/mcp.rs): external bridge · MCP, remote execution, hooks, plugin lifecycle, and OAuth-style connectivity. · `rust/crates/runtime/src/mcp.rs`
- [Context](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/runtime/src/git_context.rs): workspace context · Git/worktree state, prompts, config, bootstrap, and execution context management. · `rust/crates/runtime/src/git_context.rs`
- [Provider API](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/api/src/lib.rs): model boundary · HTTP clients, streaming, prompt caching, errors, and provider adapters for model endpoints. · `rust/crates/api/src/lib.rs`
- [Providers](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/api/src/providers/mod.rs): adapter layer · Anthropic and OpenAI-compatible provider implementations. · `rust/crates/api/src/providers/mod.rs`
- [Transport](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/api/src/http_client.rs): http/sse plumbing · HTTP client behavior and streaming/SSE handling for provider communication. · `rust/crates/api/src/http_client.rs`
- [Tools](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/tools/src/lib.rs): capability modules · Reusable operational capabilities invoked by the runtime, such as lane completion and PDF extraction. · `rust/crates/tools/src/lib.rs`
- [Plugins](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/plugins/src/lib.rs): extension system · Plugin model, hook conventions, and bundled examples for constrained augmentation. · `rust/crates/plugins/src/lib.rs`
- [Telemetry](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/telemetry/src/lib.rs): usage reporting · Usage and telemetry support for observing agent activity. · `rust/crates/telemetry/src/lib.rs`

### Python reference

Parity, migration, and reference workspace under src/

- [Python tree](https://github.com/selvin-paul-raj/claw-code/blob/main/src/main.py): reference workspace · Python reference implementation used for parity auditing, subsystem snapshots, and migration helpers. · `src/main.py`
- [Parity audit](https://github.com/selvin-paul-raj/claw-code/blob/main/src/parity_audit.py): comparison tooling · Audit and reference-data tooling that compares subsystems and behavior against snapshots. · `src/parity_audit.py`

### Validation and delivery

CI, parity harnesses, containerization, and release support

- [Parity harness](https://github.com/selvin-paul-raj/claw-code/blob/main/rust/crates/compat-harness/src/lib.rs): test harness · Mock services and compatibility harnesses for deterministic comparison and migration checks. · `rust/crates/compat-harness/src/lib.rs`
- [CI & release](https://github.com/selvin-paul-raj/claw-code/blob/main/.github/workflows/rust-ci.yml): delivery pipeline · Workflow, release, documentation checks, and containerized build delivery. · `.github/workflows/rust-ci.yml`

## Connections

- CLI shell → Input: parse · CLI parses commands and interactive input.
- CLI shell → Render: render · CLI presents output and streamed responses.
- CLI shell → Startup: bootstrap · CLI initializes defaults and startup state.
- CLI shell → Runtime core: delegate · User-facing commands hand off to the runtime control plane.
- Runtime core → Sessions: manage · Runtime maintains sessions, tasks, transcripts, and recovery state.
- Runtime core → Policy: enforce · Runtime wraps execution in permissions, trust, and sandbox policy.
- Runtime core → Integrations: bridge · Runtime reaches MCP, plugins, hooks, OAuth, and remote integrations.
- Runtime core → Context: context · Runtime builds execution context from config, git, prompts, and bootstrap data.
- Runtime core → Provider API: call · Runtime sends model/provider requests through the API boundary.
- Runtime core → Tools: invoke · Runtime can execute reusable tools as capabilities.
- Runtime core → Telemetry: emit · Runtime records usage and telemetry signals.
- Provider API → Transport: transport · API layer handles HTTP and streaming mechanics.
- Provider API → Providers: adapt · API exposes provider-specific adapters behind one boundary.
- Integrations → Plugins: load · Plugins are loaded and constrained through lifecycle and hooks.
- Integrations → Parity harness: exercise · Integration and parity harnesses validate external behaviors.
- Python tree → Parity audit: audit · Python reference workspace supports parity and subsystem snapshots.
- Parity harness → Provider API: mock · Mock services stand in for provider communication during parity tests.
- Parity harness → Runtime core: compare · Harnesses compare runtime behavior against reference scenarios.
- Parity audit → Parity harness: check · Audit tooling feeds and inspects deterministic harness outputs.
- CI & release → Parity harness: validate · CI and release flows run parity and compatibility checks.
- CI & release → Python tree: verify · Operational checks include source-of-truth and reference validation.
