# ultraworkers/claw-code-parity architecture

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

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

## Overview

1. **Repo shape**
   - This repository is a **two-track porting workspace**: a current **Python-first analysis/porting tree** under `src/`, and a larger **Rust monorepo** under `rust/` that is the in-progress runtime rewrite.
   - The Python side is primarily for **workspace manifesting, subsystem summaries, and parity auditing**; the Rust side contains the actual execution architecture.

2. **Python workspace: metadata and parity layer**
   - `src/main.py`, `query_engine.py`, `port_manifest.py`, `models.py`, `commands.py`, and `tools.py` form a lightweight CLI/analysis layer.
   - It reads from `src/reference_data/` snapshots and emits summaries such as subsystem inventories, command/tool inventories, and parity audits.
   - This layer is not the main runtime; it is a **porting and verification surface** for comparing the current workspace against archived structure.

3. **Python subsystem mirror**
   - The Python tree includes namespace-style modules such as `assistant`, `bootstrap`, `bridge`, `coordinator`, `server`, `remote`, `plugins`, `skills`, `state`, `voice`, `vim`, and others.
   - Architecturally, these look like **mirrored subsystem boundaries** from the original harness rather than a single layered application.
   - If you draw the diagram, treat these as **logical subsystems grouped under a porting workspace**, with `reference_data` providing the structural baseline.

4. **Rust monorepo: main executable architecture**
   - The Rust workspace under `rust/` is organized as multiple crates: `rusty-claude-cli`, `runtime`, `api`, `plugins`, `tools`, `telemetry`, `mock-anthropic-service`, and `compat-harness`.
   - This is the clearest “production” architecture in the repo: a **CLI front end**, a **runtime core**, an **API/provider layer**, and **supporting test/mocking/tooling crates**.

5. **CLI boundary**
   - `rust/crates/rusty-claude-cli` is the user-facing entrypoint.
   - Its modules (`args`, `input`, `render`, `init`, `app`) indicate a boundary that handles **argument parsing, terminal/input behavior, rendering, and app bootstrap**, then hands off to the runtime.
   - On the Python side, `src/main.py` plays a smaller analogous role for manifest/query commands.

6. **Runtime core**
   - `rust/crates/runtime` is the central orchestration layer.
   - Its modules cover **bootstrap, config, conversation/session management, prompt handling, compacting, permissions, sandboxing, file operations, hooks, remote execution, usage tracking, task registries, and team cron registries**.
   - This is the heart of the system: it coordinates the agent lifecycle, enforces boundaries, and moves state across sessions and tool interactions.

7. **Provider/API integration**
   - `rust/crates/api` abstracts model-provider communication.
   - It includes provider implementations for **Anthropic** and **OpenAI-compatible** APIs, plus **SSE streaming**, prompt caching, typed request/response models, and error handling.
   - This crate is the network-facing boundary where the runtime turns conversation state into streamed model calls and receives incremental output back.

8. **Tools, MCP, and external execution**
   - The Rust runtime includes **MCP client/stdin-stdio/tool bridge** modules and a separate `tools` crate.
   - This indicates a tool-execution path where the runtime can invoke external capabilities through a structured bridge rather than embedding everything in the CLI.
   - In architecture terms, this is the **agent tool plane**: runtime → tool bridge/MCP → external tool/process/service.

9. **Plugins and hooks**
   - `rust/crates/plugins` plus bundled examples show a plugin/hook system with `pre.sh` and `post.sh` style lifecycle hooks.
   - The runtime’s `hooks` module likely mediates when those hooks run, making hooks a cross-cutting extension point rather than a separate subsystem.
   - For a diagram, represent hooks/plugins as **extension boundaries attached to runtime events**.

10. **Testing, mocks, and parity harness**
   - `rust/crates/mock-anthropic-service` and `rust/crates/compat-harness` provide a local test/mocking layer for API compatibility and parity checks.
   - Rust tests and scripts under `rust/scripts/` support **mock parity runs** and diffing behavior against scenarios.
   - The top-level `.github/workflows/rust-ci.yml` reinforces that verification is a first-class architectural concern.

11. **Primary data flow**
   - User input enters through the CLI, is shaped by app/input/render layers, then passed into the runtime.
   - The runtime consults config, permissions, sandbox, hooks, and tool bridges, and then calls model providers through the API crate.
   - Provider responses stream back into conversation/session state, with usage tracking and transcript-like state feeding subsequent turns.
   - On the Python side, the flow is different: it reads repository metadata and snapshots, then emits summaries/parity reports rather than executing the agent loop.

12. **What to emphasize in a diagram**
   - Draw the repository as **two distinct planes**:
     - a **Python porting/inspection plane** centered on manifests, reference data, and parity audits;
     - a **Rust execution plane** centered on CLI → runtime → API/providers → tools/hooks/plugins.
   - The strongest boundaries are:
     - CLI vs runtime,
     - runtime vs external providers,
     - runtime vs tools/MCP,
     - runtime vs plugins/hooks,
     - and analysis/porting code vs executable harness code.

Main entry points: [`rust/crates/runtime`](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/runtime) (Runtime), [`src/query_engine.py`](https://github.com/ultraworkers/claw-code-parity/blob/main/src/query_engine.py) (Query engine), [`rust/crates/rusty-claude-cli`](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/rusty-claude-cli) (Rust CLI), [`src/reference_data`](https://github.com/ultraworkers/claw-code-parity/tree/main/src/reference_data) (Reference data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_plane["Python porting plane"]
  node_py_main["Main CLI<br/>python entrypoint<br/>[main.py]"]
  node_py_query_engine["Query engine<br/>python analysis<br/>[query_engine.py]"]
  node_py_port_manifest["Port manifest<br/>python manifest<br/>[port_manifest.py]"]
  node_py_parity_audit["Parity audit<br/>python verifier<br/>[parity_audit.py]"]
  node_py_reference_data[("Reference data<br/>snapshot baseline")]
  node_py_assistant["Assistant<br/>mirrored subsystem"]
  node_py_server["Server<br/>mirrored subsystem"]
end

subgraph group_rust_plane["Rust execution plane"]
  node_rust_cli["Rust CLI<br/>user entrypoint"]
  node_rust_args["Args<br/>cli parsing<br/>[args.rs]"]
  node_rust_input["Input<br/>[input.rs]"]
  node_rust_render["Render<br/>[render.rs]"]
  node_rust_runtime["Runtime<br/>orchestration core"]
  node_rust_api["API<br/>provider client"]
  node_rust_tools["Tools<br/>tool crate"]
  node_rust_plugins["Plugins<br/>extension hooks"]
  node_rust_telemetry["Telemetry<br/>observability"]
  node_rust_mock["Mock service<br/>api mock"]
  node_rust_compat["Compat harness<br/>parity harness"]
  node_rust_commands["Commands<br/>command crate"]
end

node_py_main -->|"queries"| node_py_query_engine
node_py_main -->|"builds"| node_py_port_manifest
node_py_query_engine -->|"reads"| node_py_reference_data
node_py_port_manifest -->|"loads"| node_py_reference_data
node_py_parity_audit -->|"compares"| node_py_reference_data
node_py_parity_audit -->|"uses"| node_py_query_engine
node_py_query_engine -.->|"maps"| node_py_assistant
node_py_query_engine -.->|"maps"| node_py_server
node_rust_cli -->|"parses"| node_rust_args
node_rust_cli -->|"reads"| node_rust_input
node_rust_cli -->|"renders"| node_rust_render
node_rust_cli -->|"hands off"| node_rust_runtime
node_rust_runtime -->|"calls"| node_rust_api
node_rust_runtime -->|"invokes"| node_rust_tools
node_rust_runtime -->|"extends"| node_rust_plugins
node_rust_runtime -->|"dispatches"| node_rust_commands
node_rust_runtime -->|"tracks"| node_rust_telemetry
node_rust_runtime -.->|"tests against"| node_rust_mock
node_rust_runtime -.->|"verified by"| node_rust_compat
node_rust_api -.->|"targets"| node_rust_mock

click node_py_main "https://github.com/ultraworkers/claw-code-parity/blob/main/src/main.py"
click node_py_query_engine "https://github.com/ultraworkers/claw-code-parity/blob/main/src/query_engine.py"
click node_py_port_manifest "https://github.com/ultraworkers/claw-code-parity/blob/main/src/port_manifest.py"
click node_py_parity_audit "https://github.com/ultraworkers/claw-code-parity/blob/main/src/parity_audit.py"
click node_py_reference_data "https://github.com/ultraworkers/claw-code-parity/tree/main/src/reference_data"
click node_py_assistant "https://github.com/ultraworkers/claw-code-parity/tree/main/src/assistant"
click node_py_server "https://github.com/ultraworkers/claw-code-parity/tree/main/src/server"
click node_rust_cli "https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/rusty-claude-cli"
click node_rust_args "https://github.com/ultraworkers/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/src/args.rs"
click node_rust_input "https://github.com/ultraworkers/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/src/input.rs"
click node_rust_render "https://github.com/ultraworkers/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/src/render.rs"
click node_rust_runtime "https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/runtime"
click node_rust_api "https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/api"
click node_rust_tools "https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/tools"
click node_rust_plugins "https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/plugins"
click node_rust_telemetry "https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/telemetry"
click node_rust_mock "https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/mock-anthropic-service"
click node_rust_compat "https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/compat-harness"
click node_rust_commands "https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/commands"

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_engine,node_py_port_manifest,node_py_parity_audit,node_py_reference_data,node_py_assistant,node_py_server toneBlue
class node_rust_cli,node_rust_args,node_rust_input,node_rust_render,node_rust_runtime,node_rust_api,node_rust_tools,node_rust_plugins,node_rust_telemetry,node_rust_mock,node_rust_compat,node_rust_commands toneAmber
```

## Components

### Python porting plane

Manifesting, snapshot lookup, and parity auditing around mirrored subsystem metadata.

- [Main CLI](https://github.com/ultraworkers/claw-code-parity/blob/main/src/main.py): python entrypoint · Lightweight command entrypoint for manifesting and query flows. · `src/main.py`
- [Query engine](https://github.com/ultraworkers/claw-code-parity/blob/main/src/query_engine.py): python analysis · Resolves repository structure and powers subsystem or command queries. · `src/query_engine.py`
- [Port manifest](https://github.com/ultraworkers/claw-code-parity/blob/main/src/port_manifest.py): python manifest · Builds workspace summaries and porting inventories from known structure. · `src/port_manifest.py`
- [Parity audit](https://github.com/ultraworkers/claw-code-parity/blob/main/src/parity_audit.py): python verifier · Compares current workspace structure against archived snapshots. · `src/parity_audit.py`
- [Reference data](https://github.com/ultraworkers/claw-code-parity/tree/main/src/reference_data): snapshot baseline · Archived subsystem and tool snapshots used as the structural source of truth. · `src/reference_data`
- [Assistant](https://github.com/ultraworkers/claw-code-parity/tree/main/src/assistant): mirrored subsystem · Representative mirrored subsystem boundary from the ported Python tree. · `src/assistant`
- [Server](https://github.com/ultraworkers/claw-code-parity/tree/main/src/server): mirrored subsystem · Representative server-side subsystem boundary in the mirrored Python workspace. · `src/server`

### Rust execution plane

Production CLI, runtime, provider, tool, plugin, and verification crates.

- [Rust CLI](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/rusty-claude-cli): user entrypoint · User-facing executable that parses input, renders output, and boots the app. · `rust/crates/rusty-claude-cli`
- [Args](https://github.com/ultraworkers/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/src/args.rs): cli parsing · Argument and flag handling for the Rust front end. · `rust/crates/rusty-claude-cli/src/args.rs`
- [Input](https://github.com/ultraworkers/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/src/input.rs): terminal input · Interactive input and prompt handling at the CLI boundary. · `rust/crates/rusty-claude-cli/src/input.rs`
- [Render](https://github.com/ultraworkers/claw-code-parity/blob/main/rust/crates/rusty-claude-cli/src/render.rs): tui rendering · Terminal rendering and presentation for the executable UI. · `rust/crates/rusty-claude-cli/src/render.rs`
- [Runtime](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/runtime): orchestration core · Central execution layer for sessions, permissions, sandboxing, hooks, and task flow. · `rust/crates/runtime`
- [API](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/api): provider client · Model-provider integration layer with streaming, caching, and typed request/response models. · `rust/crates/api`
- [Tools](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/tools): tool crate · Shared tool surface used by runtime-adjacent execution and integrations. · `rust/crates/tools`
- [Plugins](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/plugins): extension hooks · Plugin and hook package with bundled lifecycle hook examples. · `rust/crates/plugins`
- [Telemetry](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/telemetry): observability · Support crate for runtime observability and tracking. · `rust/crates/telemetry`
- [Mock service](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/mock-anthropic-service): api mock · Local Anthropic-compatible service used for tests and parity runs. · `rust/crates/mock-anthropic-service`
- [Compat harness](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/compat-harness): parity harness · Compatibility harness for replaying scenarios and checking behavioral parity. · `rust/crates/compat-harness`
- [Commands](https://github.com/ultraworkers/claw-code-parity/tree/main/rust/crates/commands): command crate · Shared command surface used by the Rust workspace. · `rust/crates/commands`

## Connections

- Main CLI → Query engine: queries · CLI entrypoint delegates repository lookups and summaries to the analysis layer.
- Main CLI → Port manifest: builds · Entry commands emit workspace manifests and inventory views.
- Query engine → Reference data: reads · Queries resolve against archived snapshots and subsystem baselines.
- Port manifest → Reference data: loads · Manifest generation consumes stored reference snapshots.
- Parity audit → Reference data: compares · Parity checks diff current structure against archived data.
- Parity audit → Query engine: uses · Audits rely on query results for structural comparison.
- Query engine → Assistant: maps · Subsystem queries surface mirrored boundaries such as assistant.
- Query engine → Server: maps · Subsystem queries surface mirrored boundaries such as server.
- Rust CLI → Args: parses · The executable begins with flag and argument parsing.
- Rust CLI → Input: reads · Interactive flows pull terminal input through the CLI boundary.
- Rust CLI → Render: renders · Output presentation is handled before handing off to runtime work.
- Rust CLI → Runtime: hands off · CLI bootstrap transfers control into the runtime core.
- Runtime → API: calls · Runtime turns conversation state into provider requests and streams responses back.
- Runtime → Tools: invokes · Runtime uses the tool plane for external capabilities and execution bridges.
- Runtime → Plugins: extends · Hooks and plugins attach to runtime events and lifecycle points.
- Runtime → Commands: dispatches · Shared commands are consumed as part of runtime control flow.
- Runtime → Telemetry: tracks · Usage and observability data are emitted from the core runtime.
- Runtime → Mock service: tests against · Mock provider service supports local verification and parity runs.
- Runtime → Compat harness: verified by · Compatibility harness exercises runtime behavior against scenarios.
- API → Mock service: targets · Provider client tests can target the local mock service.
