# instructkr/claw-code architecture

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

- Interactive diagram: https://gitdiagram.com/instructkr/claw-code
- Repository: https://github.com/instructkr/claw-code

## Overview

1. **This repo has two distinct layers**
   - The **Python tree under `src/`** is the current porting/analysis workspace.
   - The **Rust workspace under `rust/`** is the executable systems-language implementation of the harness.
   - Architecturally, the Python side is mostly **metadata, parity tracking, and reporting**, while the Rust side contains the **runtime, CLI, integrations, and provider clients**.

2. **Python `src/` is a porting control plane, not the main runtime**
   - Key modules like `port_manifest.py`, `query_engine.py`, `commands.py`, `tools.py`, and `models.py` describe and summarize the workspace.
   - `main.py` exposes commands such as summary, manifest, subsystem listing, commands/tools inventories, and parity audit.
   - This layer reads local reference data and produces high-level views of the project structure for verification and migration tracking.

3. **Reference data is the Python side’s main input**
   - `src/reference_data/` contains snapshots for subsystems, commands, tools, and archive surfaces.
   - These snapshots are used to compare the current Python workspace against the archived/expected surface area.
   - The `tests/` directory validates this porting workspace rather than exercising the full agent runtime.

4. **Rust is the main productized architecture**
   - The Rust workspace is split into focused crates: `api`, `runtime`, `tools`, `commands`, `plugins`, `claw-cli`, `server`, `lsp`, `compat-harness`, and `compat-harness`.
   - This is a layered design: **interface entrypoints** at the top, **runtime orchestration** in the middle, and **provider/tool/plugin integrations** at the edges.

5. **`crates/claw-cli` is the primary user-facing entrypoint**
   - It provides the interactive CLI, argument parsing, input handling, rendering, and project bootstrap/init flows.
   - In the diagram, this is the main human-facing boundary: user input enters here, then flows into runtime/session orchestration.

6. **`crates/runtime` is the orchestration core**
   - This crate owns session state, conversation history, compaction, prompt construction, permissions, sandboxing, file operations, hooks, config, usage accounting, and remote/MCP integration.
   - It is the central hub where user intent, model responses, tool execution, and policy checks converge.
   - Most other runtime-facing crates either feed data into it or are invoked by it.

7. **Model/provider communication lives in `crates/api`**
   - The API crate abstracts model providers and streaming responses.
   - It includes provider implementations for a Claw-specific provider and an OpenAI-compatible path, plus OAuth and SSE/streaming support.
   - This is the external network boundary where the harness talks to model endpoints and receives incremental output.

8. **Tooling and command execution are separate subsystems**
   - `crates/tools` defines tool manifests and execution framework.
   - `crates/commands` handles slash commands, skills discovery, and config inspection.
   - These are invoked by the runtime as part of agent action handling, and they form the bridge between language-model output and actual side effects.

9. **Plugins and hooks extend behavior**
   - `crates/plugins` provides the plugin model and hook pipeline, with bundled example plugins.
   - Hooks are an explicit extension boundary: runtime events can trigger pre/post behaviors without embedding those behaviors directly into core orchestration.
   - This is a clear seam for customization and policy enforcement.

10. **There are two additional integration surfaces besides the CLI**
   - `crates/server` provides an HTTP/SSE-style server boundary for remote or programmatic access.
   - `crates/lsp` integrates with editor workflows through an LSP client/manager.
   - `crates/compat-harness` exists as a compatibility layer for upstream editor or harness expectations.

11. **MCP, OAuth, remote, and sandboxing are important external boundaries**
   - The runtime includes MCP client/stdio support, remote execution plumbing, OAuth, and sandbox components.
   - These are the boundaries where the harness interacts with external tools, local environment constraints, or authenticated services.
   - For an architecture diagram, these should be drawn as off-core dependencies connected to the runtime.

12. **The typical runtime data flow is:**
   - user enters via **CLI / server / LSP**
   - runtime loads **session/config/permissions**
   - prompt is built and sent through **API providers**
   - streamed model output comes back
   - runtime may invoke **commands, tools, MCP, hooks, plugins, file ops, or sandboxed actions**
   - results are folded back into **conversation/session state** and usage tracking.

13. **The repository also includes verification and parity tooling**
   - Rust CI lives under `rust/.github/workflows`.
   - Python verification is lightweight and centered on the porting workspace.
   - The presence of snapshots and parity audit tooling indicates that architectural fidelity is a first-class concern, not just functionality.

14. **How to draw it**
   - Put the **Rust runtime** in the center.
   - Put **CLI / server / LSP** on the ingress side.
   - Put **API providers** on the egress side.
   - Attach **tools, commands, plugins, hooks, MCP, sandbox, OAuth, remote** around the runtime as extension and integration boundaries.
   - Treat the **Python `src/` tree** as a separate analysis/parity subsystem that observes and summarizes the architecture rather than executing the harness itself.

Main entry points: [`rust/crates/runtime/src/lib.rs`](https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/lib.rs) (Runtime core), [`rust/crates/runtime/src/file_ops.rs`](https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/file_ops.rs) (Execution boundary), [`rust/crates/lsp/src/lib.rs`](https://github.com/instructkr/claw-code/blob/main/rust/crates/lsp/src/lib.rs) (LSP), [`src/main.py`](https://github.com/instructkr/claw-code/blob/main/src/main.py) (Port CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_control["Python porting workspace"]
  node_py_main["Port CLI<br/>python entrypoint<br/>[main.py]"]
  node_py_manifest["Manifest<br/>workspace model<br/>[port_manifest.py]"]
  node_py_query["Query engine<br/>analysis engine<br/>[query_engine.py]"]
  node_py_summaries["Surface views<br/>inventory/reporting<br/>[commands.py]"]
  node_py_models["Models<br/>[models.py]"]
  node_py_reference[("Snapshots<br/>reference data")]
  node_py_parity["Parity audit<br/>verification<br/>[parity_audit.py]"]
  node_py_tests["Port tests<br/>verification tests"]
end

subgraph group_rust_product["Rust product workspace"]
  node_cli["CLI<br/>rust entrypoint<br/>[main.rs]"]
  node_runtime_core{{"Runtime core<br/>orchestrator<br/>[lib.rs]"}}
  node_runtime_session["Session state<br/>state management<br/>[session.rs]"]
  node_runtime_prompt["Prompt/policy<br/>prompting<br/>[prompt.rs]"]
  node_runtime_exec["Execution boundary<br/>side effects<br/>[file_ops.rs]"]
  node_runtime_usage["Usage tracking<br/>accounting<br/>[usage.rs]"]
  node_api[("API layer<br/>model providers<br/>[lib.rs]")]
  node_api_providers["Providers<br/>provider adapters<br/>[mod.rs]"]
  node_tools["Tools<br/>tooling framework<br/>[lib.rs]"]
  node_commands["Commands<br/>[lib.rs]"]
  node_plugins["Plugins<br/>extension system<br/>[lib.rs]"]
end

subgraph group_integrations["Integration surfaces"]
  node_server["Server<br/>remote ingress<br/>[lib.rs]"]
  node_lsp["LSP<br/>editor integration<br/>[lib.rs]"]
  node_compat["Compat harness<br/>compatibility layer<br/>[lib.rs]"]
end

node_py_main -->|"builds"| node_py_manifest
node_py_main -->|"uses"| node_py_query
node_py_query -->|"compares"| node_py_reference
node_py_parity -->|"checks"| node_py_reference
node_py_summaries -->|"formats"| node_py_models
node_py_tests -->|"validates"| node_py_parity
node_cli -->|"enters"| node_runtime_core
node_server -->|"enters"| node_runtime_core
node_lsp -->|"enters"| node_runtime_core
node_runtime_core -->|"manages"| node_runtime_session
node_runtime_core -->|"builds"| node_runtime_prompt
node_runtime_core -->|"dispatches"| node_runtime_exec
node_runtime_core -->|"tracks"| node_runtime_usage
node_runtime_core -->|"calls"| node_api
node_api -->|"selects"| node_api_providers
node_runtime_core -->|"invokes"| node_tools
node_runtime_core -->|"executes"| node_commands
node_runtime_core -->|"extends"| node_plugins
node_plugins -.->|"hooks"| node_runtime_core
node_runtime_exec -.->|"integrates"| node_server
node_runtime_exec -.->|"integrates"| node_lsp
node_compat -->|"adapts"| node_lsp

click node_py_main "https://github.com/instructkr/claw-code/blob/main/src/main.py"
click node_py_manifest "https://github.com/instructkr/claw-code/blob/main/src/port_manifest.py"
click node_py_query "https://github.com/instructkr/claw-code/blob/main/src/query_engine.py"
click node_py_summaries "https://github.com/instructkr/claw-code/blob/main/src/commands.py"
click node_py_models "https://github.com/instructkr/claw-code/blob/main/src/models.py"
click node_py_reference "https://github.com/instructkr/claw-code/tree/main/src/reference_data"
click node_py_parity "https://github.com/instructkr/claw-code/blob/main/src/parity_audit.py"
click node_py_tests "https://github.com/instructkr/claw-code/blob/main/tests/test_porting_workspace.py"
click node_cli "https://github.com/instructkr/claw-code/blob/main/rust/crates/claw-cli/src/main.rs"
click node_runtime_core "https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/lib.rs"
click node_runtime_session "https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/session.rs"
click node_runtime_prompt "https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/prompt.rs"
click node_runtime_exec "https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/file_ops.rs"
click node_runtime_usage "https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/usage.rs"
click node_api "https://github.com/instructkr/claw-code/blob/main/rust/crates/api/src/lib.rs"
click node_api_providers "https://github.com/instructkr/claw-code/blob/main/rust/crates/api/src/providers/mod.rs"
click node_tools "https://github.com/instructkr/claw-code/blob/main/rust/crates/tools/src/lib.rs"
click node_commands "https://github.com/instructkr/claw-code/blob/main/rust/crates/commands/src/lib.rs"
click node_plugins "https://github.com/instructkr/claw-code/blob/main/rust/crates/plugins/src/lib.rs"
click node_server "https://github.com/instructkr/claw-code/blob/main/rust/crates/server/src/lib.rs"
click node_lsp "https://github.com/instructkr/claw-code/blob/main/rust/crates/lsp/src/lib.rs"
click node_compat "https://github.com/instructkr/claw-code/blob/main/rust/crates/compat-harness/src/lib.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_py_main,node_py_manifest,node_py_query,node_py_summaries,node_py_models,node_py_reference,node_py_parity,node_py_tests toneBlue
class node_cli,node_runtime_core,node_runtime_session,node_runtime_prompt,node_runtime_exec,node_runtime_usage,node_api,node_api_providers,node_tools,node_commands,node_plugins toneAmber
class node_server,node_lsp,node_compat toneMint
```

## Components

### Python porting workspace

Analysis, parity tracking, and surface-area reporting for the ported workspace.

- [Port CLI](https://github.com/instructkr/claw-code/blob/main/src/main.py): python entrypoint · Top-level commands for summaries, manifests, inventories, and parity audits. · `src/main.py`
- [Manifest](https://github.com/instructkr/claw-code/blob/main/src/port_manifest.py): workspace model · Describes the ported workspace surface and how it is tracked. · `src/port_manifest.py`
- [Query engine](https://github.com/instructkr/claw-code/blob/main/src/query_engine.py): analysis engine · Queries the local workspace and reference snapshots to build reports. · `src/query_engine.py`
- [Surface views](https://github.com/instructkr/claw-code/blob/main/src/commands.py): inventory/reporting · Command and tool summaries plus structured workspace views. · `src/commands.py`
- [Models](https://github.com/instructkr/claw-code/blob/main/src/models.py): data models · Shared Python-side structures for workspace, parity, and reporting data. · `src/models.py`
- [Snapshots](https://github.com/instructkr/claw-code/tree/main/src/reference_data): reference data · Archived subsystems, commands, tools, and surface snapshots used for comparison. · `src/reference_data`
- [Parity audit](https://github.com/instructkr/claw-code/blob/main/src/parity_audit.py): verification · Checks the current porting workspace against expected reference surfaces. · `src/parity_audit.py`
- [Port tests](https://github.com/instructkr/claw-code/blob/main/tests/test_porting_workspace.py): verification tests · Validates the Python porting workspace and snapshot-driven expectations. · `tests/test_porting_workspace.py`

### Rust product workspace

Executable harness implementation and runtime orchestration.

- [CLI](https://github.com/instructkr/claw-code/blob/main/rust/crates/claw-cli/src/main.rs): rust entrypoint · Human-facing command line boundary for input, rendering, and bootstrap flows. · `rust/crates/claw-cli/src/main.rs`
- [Runtime core](https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/lib.rs): orchestrator · Coordinates sessions, conversation flow, policies, tools, and execution. · `rust/crates/runtime/src/lib.rs`
- [Session state](https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/session.rs): state management · Owns session lifecycle, conversation history, and compaction. · `rust/crates/runtime/src/session.rs`
- [Prompt/policy](https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/prompt.rs): prompting · Builds prompts and applies permissions, config, and policy boundaries. · `rust/crates/runtime/src/prompt.rs`
- [Execution boundary](https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/file_ops.rs): side effects · File ops, sandboxing, remote/MCP, OAuth, and other action boundaries. · `rust/crates/runtime/src/file_ops.rs`
- [Usage tracking](https://github.com/instructkr/claw-code/blob/main/rust/crates/runtime/src/usage.rs): accounting · Tracks usage, usage-related state, and response accounting. · `rust/crates/runtime/src/usage.rs`
- [API layer](https://github.com/instructkr/claw-code/blob/main/rust/crates/api/src/lib.rs): model providers · Streaming model provider abstraction and external endpoint integration. · `rust/crates/api/src/lib.rs`
- [Providers](https://github.com/instructkr/claw-code/blob/main/rust/crates/api/src/providers/mod.rs): provider adapters · Concrete provider implementations and compatibility paths for model calls. · `rust/crates/api/src/providers/mod.rs`
- [Tools](https://github.com/instructkr/claw-code/blob/main/rust/crates/tools/src/lib.rs): tooling framework · Defines tool manifests and execution framework used by the runtime. · `rust/crates/tools/src/lib.rs`
- [Commands](https://github.com/instructkr/claw-code/blob/main/rust/crates/commands/src/lib.rs): slash commands · Handles slash commands, skills discovery, and config inspection. · `rust/crates/commands/src/lib.rs`
- [Plugins](https://github.com/instructkr/claw-code/blob/main/rust/crates/plugins/src/lib.rs): extension system · Plugin model and hook pipeline for bundled and external extensions. · `rust/crates/plugins/src/lib.rs`

### Integration surfaces

External entrypoints and extension boundaries around the runtime.

- [Server](https://github.com/instructkr/claw-code/blob/main/rust/crates/server/src/lib.rs): remote ingress · HTTP/SSE-style boundary for programmatic or remote access. · `rust/crates/server/src/lib.rs`
- [LSP](https://github.com/instructkr/claw-code/blob/main/rust/crates/lsp/src/lib.rs): editor integration · Editor workflow integration through an LSP client/manager. · `rust/crates/lsp/src/lib.rs`
- [Compat harness](https://github.com/instructkr/claw-code/blob/main/rust/crates/compat-harness/src/lib.rs): compatibility layer · Compatibility layer for upstream editor or harness expectations. · `rust/crates/compat-harness/src/lib.rs`

## Connections

- Port CLI → Manifest: builds · Creates summaries and manifests from the workspace.
- Port CLI → Query engine: uses · Runs workspace queries for inventories and audits.
- Query engine → Snapshots: compares · Compares current state with stored snapshots.
- Parity audit → Snapshots: checks · Uses reference snapshots for parity validation.
- Surface views → Models: formats · Turns structured workspace data into reports.
- Port tests → Parity audit: validates · Exercises parity and porting expectations.
- CLI → Runtime core: enters · Primary user-facing input flows into runtime orchestration.
- Server → Runtime core: enters · Remote requests are handled by the runtime.
- LSP → Runtime core: enters · Editor-driven workflows feed into the runtime.
- Runtime core → Session state: manages · Owns session lifecycle and conversation state.
- Runtime core → Prompt/policy: builds · Constructs prompts and applies policy constraints.
- Runtime core → Execution boundary: dispatches · Invokes execution, file, sandbox, remote, and auth boundaries.
- Runtime core → Usage tracking: tracks · Records usage and accounting information.
- Runtime core → API layer: calls · Sends prompts and receives streamed model output.
- API layer → Providers: selects · Routes requests to provider-specific implementations.
- Runtime core → Tools: invokes · Executes agent tools as part of action handling.
- Runtime core → Commands: executes · Resolves slash commands and command-side workflows.
- Runtime core → Plugins: extends · Triggers hooks and plugin behaviors around runtime events.
- Plugins → Runtime core: hooks · Plugin hooks can observe or modify runtime events.
- Execution boundary → Server: integrates · Remote-oriented execution paths connect to programmatic access.
- Execution boundary → LSP: integrates · Editor-facing runtime actions connect through LSP workflows.
- Compat harness → LSP: adapts · Compatibility layer supports upstream/editor expectations.
