# soubankunnummel/claw-code-parity architecture

> Architecture diagram of the GitHub repository soubankunnummel/claw-code-parity, 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/soubankunnummel/claw-code-parity
- Repository: https://github.com/soubankunnummel/claw-code-parity

## Overview

1. **Repository shape**
   This repo is split into two architectural layers:
   - `src/` is the active **Python porting workspace** used to model and inspect the original harness structure.
   - `rust/` is a much more complete **Rust workspace** for the harness runtime itself, with CLI, runtime, API clients, plugins, and supporting crates.

2. **Python layer = analysis / parity workspace**
   The top-level Python package is not just application logic; it is a **porting and inventory system**. Its main job is to represent the source tree as data, compare it to archived snapshots, and render summaries for parity work.
   Key entry points are `src/main.py`, `src/query_engine.py`, and `src/port_manifest.py`.

3. **Python data model and reporting flow**
   The Python flow is:
   archived/reference snapshots and workspace metadata -> `models.py` / `port_manifest.py` -> `query_engine.py` -> CLI output in `main.py`.
   Supporting modules like `commands.py`, `tools.py`, `task.py`, `query.py`, `session_store.py`, and `parity_audit.py` suggest the Python tree is centered on **summarization, inspection, and parity checks**, not on running the full agent harness.

4. **Python subsystem mirroring**
   The Python package is organized into many subsystem-named packages such as `assistant`, `bootstrap`, `bridge`, `coordinator`, `remote`, `server`, `services`, `state`, `plugins`, `vim`, and `voice`. This mirrors the structure of the original harness and gives the porting workspace a **module-by-module mapping**.
   The `src/reference_data/subsystems/*.json` files are especially important: they act as the expected surface for these mirrored subsystems.

5. **Reference and verification layer**
   The Python workspace includes snapshots such as `archive_surface_snapshot.json`, `commands_snapshot.json`, and `tools_snapshot.json`, plus a `tests/` directory with parity-focused checks.  
   This creates a clear validation boundary: **workspace introspection code** is compared against **frozen reference data** to measure how close the port is to the archived system.

6. **Rust workspace = operational harness**
   The Rust side is organized as a Cargo workspace with distinct crates for major concerns:
   - `rusty-claude-cli` for the user-facing CLI
   - `runtime` for agent/session orchestration
   - `api` for provider/network integration
   - `plugins` for hook/plugin loading
   - `commands` for command handling
   - `telemetry` for usage reporting
   - `compat-harness` and `tools` for support and compatibility work

7. **Rust execution path**
   In Rust, the typical flow is:
   CLI arguments and input parsing -> `rusty-claude-cli` -> runtime orchestration -> API/provider calls and tool execution -> session/output rendering.
   The CLI crate is the top boundary; `app.rs`, `args.rs`, `input.rs`, `render.rs`, and `init.rs` indicate that it handles startup, command parsing, and terminal interaction before handing control to the runtime crate.

8. **Rust runtime orchestration**
   The `runtime` crate is the main coordination layer. Its modules show the core harness responsibilities:
   - `bootstrap`, `config`, and `session` for startup and persistence
   - `conversation`, `prompt`, and `compact` for turn/state management
   - `permissions`, `sandbox`, and `file_ops` for local execution boundaries
   - `hooks` for extension points
   - `remote`, `mcp`, `mcp_client`, and `mcp_stdio` for external tool/service integration
   - `usage` for metering
   This is the central boundary between user intent and agent execution.

9. **Provider and streaming boundary**
   The `api` crate isolates external model/provider concerns. It includes provider-specific clients for **Anthropic** and **OpenAI-compatible** endpoints, plus SSE streaming, prompt caching, error handling, and typed request/response structures.
   Architecturally, this keeps the runtime independent from the specifics of each upstream AI provider.

10. **Extensibility and tool ecosystem**
   The `plugins` crate, bundled example plugins, and the runtime hook system show that the harness is designed around **pre/post command hooks and plugin-based extension**.  
   This is reinforced by the presence of MCP clients and stdio transport support, which indicate that tools can be attached both locally and over structured protocol boundaries.

11. **Operational support and compatibility**
   `telemetry` tracks usage signals, while `compat-harness` and `tools` support migration/interop work. The `tests/` in both Python and Rust, plus GitHub Actions (`.github/workflows/rust-ci.yml`), make validation part of the architecture rather than an afterthought.

12. **How to draw the architecture**
   A good diagram would show:
   - a **Python parity/analysis plane** built around reference data, manifests, and query/reporting
   - a **Rust execution plane** with CLI at the edge, runtime in the center, API/provider clients on one side, and tools/plugins/sandbox/remote/MCP on the other
   - snapshots/tests/CI as the verification boundary
   The key distinction is that the Python tree models and measures the system, while the Rust tree implements the actual harness runtime.

Main entry points: [`rust/crates/runtime/src/lib.rs`](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/runtime/src/lib.rs) (Runtime core), [`src/query_engine.py`](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/query_engine.py) (Query engine), [`src/parity_audit.py`](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/parity_audit.py) (Parity audit), [`rust/crates/rusty-claude-cli/src/main.rs`](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/src/main.rs) (Rust CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python parity plane"]
  node_py_main["CLI entry<br/>python entrypoint<br/>[main.py]"]
  node_py_query["Query engine<br/>python analysis<br/>[query_engine.py]"]
  node_py_manifest["Port manifest<br/>python model<br/>[port_manifest.py]"]
  node_py_models["Models<br/>python schema<br/>[models.py]"]
  node_py_audit["Parity audit<br/>python validation<br/>[parity_audit.py]"]
  node_py_session[("Session store<br/>python state<br/>[session_store.py]")]
  node_py_commands["Commands<br/>python inventory<br/>[commands.py]"]
end

subgraph group_rust["Rust execution plane"]
  node_rs_cli["Rust CLI<br/>rust entrypoint<br/>[main.rs]"]
  node_rs_runtime["Runtime core<br/>rust orchestration<br/>[lib.rs]"]
  node_rs_api["API client<br/>rust provider layer<br/>[lib.rs]"]
  node_rs_plugins["Plugins<br/>rust extensibility<br/>[lib.rs]"]
  node_rs_commands["Commands crate<br/>rust command layer<br/>[lib.rs]"]
  node_rs_telemetry["Telemetry<br/>rust metrics<br/>[lib.rs]"]
  node_rs_compat["Compat tools<br/>rust support<br/>[lib.rs]"]
  node_rs_tools["Tools crate<br/>rust support<br/>[lib.rs]"]
end

subgraph group_verify["Verification boundary"]
  node_py_reference["Reference data<br/>frozen snapshots<br/>[assistant.json]"]
  node_py_snapshot["Surface snapshot<br/>frozen snapshot"]
  node_py_tests["Parity tests<br/>python tests"]
  node_rs_api_tests["API tests<br/>rust tests"]
  node_rs_cli_tests["CLI tests<br/>rust tests"]
  node_ci["CI workflow<br/>[rust-ci.yml]"]
end

node_py_main -->|"runs"| node_py_query
node_py_query -->|"reads"| node_py_manifest
node_py_query -->|"structures"| node_py_models
node_py_main -->|"reports"| node_py_audit
node_py_audit -->|"compares"| node_py_reference
node_py_audit -->|"checks"| node_py_snapshot
node_py_session -.->|"persists"| node_py_query
node_py_commands -->|"feeds"| node_py_models
node_py_tests -->|"validates"| node_py_reference
node_py_tests -->|"exercises"| node_py_audit
node_rs_cli -->|"hands off"| node_rs_runtime
node_rs_cli -->|"parses"| node_rs_commands
node_rs_runtime -->|"calls"| node_rs_api
node_rs_runtime -->|"extends"| node_rs_plugins
node_rs_runtime -->|"emits"| node_rs_telemetry
node_rs_runtime -.->|"supports"| node_rs_compat
node_rs_runtime -.->|"uses"| node_rs_tools
node_rs_api -->|"verified by"| node_rs_api_tests
node_rs_cli -->|"verified by"| node_rs_cli_tests
node_ci -->|"runs"| node_rs_api_tests
node_ci -->|"runs"| node_rs_cli_tests
node_ci -.->|"runs"| node_py_tests

click node_py_main "https://github.com/soubankunnummel/claw-code-parity/blob/main/src/main.py"
click node_py_query "https://github.com/soubankunnummel/claw-code-parity/blob/main/src/query_engine.py"
click node_py_manifest "https://github.com/soubankunnummel/claw-code-parity/blob/main/src/port_manifest.py"
click node_py_models "https://github.com/soubankunnummel/claw-code-parity/blob/main/src/models.py"
click node_py_audit "https://github.com/soubankunnummel/claw-code-parity/blob/main/src/parity_audit.py"
click node_py_session "https://github.com/soubankunnummel/claw-code-parity/blob/main/src/session_store.py"
click node_py_commands "https://github.com/soubankunnummel/claw-code-parity/blob/main/src/commands.py"
click node_py_reference "https://github.com/soubankunnummel/claw-code-parity/blob/main/src/reference_data/subsystems/assistant.json"
click node_py_snapshot "https://github.com/soubankunnummel/claw-code-parity/blob/main/src/reference_data/archive_surface_snapshot.json"
click node_py_tests "https://github.com/soubankunnummel/claw-code-parity/blob/main/tests/test_porting_workspace.py"
click node_rs_cli "https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/src/main.rs"
click node_rs_runtime "https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/runtime/src/lib.rs"
click node_rs_api "https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/api/src/lib.rs"
click node_rs_plugins "https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/plugins/src/lib.rs"
click node_rs_commands "https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/commands/src/lib.rs"
click node_rs_telemetry "https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/telemetry/src/lib.rs"
click node_rs_compat "https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/compat-harness/src/lib.rs"
click node_rs_tools "https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/tools/src/lib.rs"
click node_rs_api_tests "https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/api/tests/client_integration.rs"
click node_rs_cli_tests "https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/tests/cli_flags_and_config_defaults.rs"
click node_ci "https://github.com/soubankunnummel/claw-code-parity/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_py_main,node_py_query,node_py_manifest,node_py_models,node_py_audit,node_py_session,node_py_commands toneBlue
class node_rs_cli,node_rs_runtime,node_rs_api,node_rs_plugins,node_rs_commands,node_rs_telemetry,node_rs_compat,node_rs_tools toneAmber
class node_py_reference,node_py_snapshot,node_py_tests,node_rs_api_tests,node_rs_cli_tests,node_ci toneMint
```

## Components

### Python parity plane

Analysis workspace that models the archived harness and measures porting parity.

- [CLI entry](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/main.py): python entrypoint · Top-level Python entrypoint for parity inspection and reporting. · `src/main.py`
- [Query engine](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/query_engine.py): python analysis · Aggregates workspace inventory and produces structured parity queries. · `src/query_engine.py`
- [Port manifest](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/port_manifest.py): python model · Loads and normalizes porting metadata used to compare against reference surfaces. · `src/port_manifest.py`
- [Models](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/models.py): python schema · Shared data structures for workspace inventory, subsystems, and reports. · `src/models.py`
- [Parity audit](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/parity_audit.py): python validation · Checks workspace coverage against archived snapshots and subsystem expectations. · `src/parity_audit.py`
- [Session store](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/session_store.py): python state · Persists analysis sessions and workspace inspection state. · `src/session_store.py`
- [Commands](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/commands.py): python inventory · Command surface inventory used by the parity workspace. · `src/commands.py`

### Rust execution plane

Operational harness workspace with CLI, runtime, API, plugins, and support crates.

- [Rust CLI](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/src/main.rs): rust entrypoint · User-facing command boundary for startup, parsing, rendering, and input handling. · `rust/crates/rusty-claude-cli/src/main.rs`
- [Runtime core](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/runtime/src/lib.rs): rust orchestration · Central coordination layer for bootstrap, session, conversation, permissions, hooks, remote, MCP, and usage. · `rust/crates/runtime/src/lib.rs`
- [API client](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/api/src/lib.rs): rust provider layer · Provider and streaming boundary for Anthropic and OpenAI-compatible endpoints. · `rust/crates/api/src/lib.rs`
- [Plugins](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/plugins/src/lib.rs): rust extensibility · Plugin loading and hook integration for bundled and external extensions. · `rust/crates/plugins/src/lib.rs`
- [Commands crate](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/commands/src/lib.rs): rust command layer · Command handling support shared by the runtime and CLI stack. · `rust/crates/commands/src/lib.rs`
- [Telemetry](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/telemetry/src/lib.rs): rust metrics · Usage reporting and operational telemetry collection. · `rust/crates/telemetry/src/lib.rs`
- [Compat tools](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/compat-harness/src/lib.rs): rust support · Compatibility and tooling support for migration and interop work. · `rust/crates/compat-harness/src/lib.rs`
- [Tools crate](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/tools/src/lib.rs): rust support · Shared tooling support crate for the Rust workspace. · `rust/crates/tools/src/lib.rs`

### Verification boundary

Frozen snapshots, tests, and CI that validate parity and runtime behavior.

- [Reference data](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/reference_data/subsystems/assistant.json): frozen snapshots · Archived subsystem maps and surface snapshots used as the parity baseline. · `src/reference_data/subsystems/assistant.json`
- [Surface snapshot](https://github.com/soubankunnummel/claw-code-parity/blob/main/src/reference_data/archive_surface_snapshot.json): frozen snapshot · Archived high-level surface snapshot for comparison with the current workspace. · `src/reference_data/archive_surface_snapshot.json`
- [Parity tests](https://github.com/soubankunnummel/claw-code-parity/blob/main/tests/test_porting_workspace.py): python tests · Workspace checks focused on porting and reference alignment. · `tests/test_porting_workspace.py`
- [API tests](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/api/tests/client_integration.rs): rust tests · Integration coverage for provider clients and streaming behavior. · `rust/crates/api/tests/client_integration.rs`
- [CLI tests](https://github.com/soubankunnummel/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/tests/cli_flags_and_config_defaults.rs): rust tests · Integration coverage for CLI flags, config defaults, and resume flows. · `rust/crates/rusty-claude-cli/tests/cli_flags_and_config_defaults.rs`
- [CI workflow](https://github.com/soubankunnummel/claw-code-parity/blob/main/.github/workflows/rust-ci.yml): ci · Repository validation workflow for Rust build and test automation. · `.github/workflows/rust-ci.yml`

## Connections

- CLI entry → Query engine: runs · CLI invokes the query engine for workspace inspection.
- Query engine → Port manifest: reads · Query engine uses port manifests to shape comparisons.
- Query engine → Models: structures · Shared models carry the inventory and report data.
- CLI entry → Parity audit: reports · Entrypoint surfaces parity findings and summaries.
- Parity audit → Reference data: compares · Parity audit checks live workspace surfaces against frozen subsystem references.
- Parity audit → Surface snapshot: checks · Audit compares current analysis output to archived snapshots.
- Session store → Query engine: persists · Stored sessions retain analysis state for later inspection.
- Commands → Models: feeds · Command inventory contributes to the modeled workspace surface.
- Parity tests → Reference data: validates · Tests assert the parity workspace matches the reference baseline.
- Parity tests → Parity audit: exercises · Tests cover the audit and comparison flow.
- Rust CLI → Runtime core: hands off · CLI boundary delegates execution to the runtime core.
- Rust CLI → Commands crate: parses · CLI wires command behavior into startup and interaction.
- Runtime core → API client: calls · Runtime delegates provider interaction and streaming to API clients.
- Runtime core → Plugins: extends · Runtime loads hooks and plugins for extensibility.
- Runtime core → Telemetry: emits · Runtime records usage and operational signals.
- Runtime core → Compat tools: supports · Runtime is accompanied by compatibility and migration support.
- Runtime core → Tools crate: uses · Runtime shares workspace tooling support where needed.
- API client → API tests: verified by · API integration tests cover provider clients and streaming behavior.
- Rust CLI → CLI tests: verified by · CLI integration tests cover flags, config, and resume behavior.
- CI workflow → API tests: runs · CI workflow executes API-level validation.
- CI workflow → CLI tests: runs · CI workflow executes CLI-level validation.
- CI workflow → Parity tests: runs · CI also anchors the Python parity checks.
