How soubankunnummel/claw-code-parity works
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: lib.rs Runtime core · query_engine.py Query engine · parity_audit.py Parity audit · main.rs Rust CLI
Components 21
Python parity plane
Analysis workspace that models the archived harness and measures porting parity.
- CLI entry · Top-level Python entrypoint for parity inspection and reporting.
src/main.py - Query engine · Aggregates workspace inventory and produces structured parity queries.
src/query_engine.py - Port manifest · Loads and normalizes porting metadata used to compare against reference surfaces.
src/port_manifest.py - Models · Shared data structures for workspace inventory, subsystems, and reports.
src/models.py - Parity audit · Checks workspace coverage against archived snapshots and subsystem expectations.
src/parity_audit.py - Session store · Persists analysis sessions and workspace inspection state.
src/session_store.py - Commands · 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 · User-facing command boundary for startup, parsing, rendering, and input handling.
rust/crates/rusty-claude-cli/src/main.rs - Runtime core · Central coordination layer for bootstrap, session, conversation, permissions, hooks, remote, MCP, and usage.
rust/crates/runtime/src/lib.rs - API client · Provider and streaming boundary for Anthropic and OpenAI-compatible endpoints.
rust/crates/api/src/lib.rs - Plugins · Plugin loading and hook integration for bundled and external extensions.
rust/crates/plugins/src/lib.rs - Commands crate · Command handling support shared by the runtime and CLI stack.
rust/crates/commands/src/lib.rs - Telemetry · Usage reporting and operational telemetry collection.
rust/crates/telemetry/src/lib.rs - Compat tools · Compatibility and tooling support for migration and interop work.
rust/crates/compat-harness/src/lib.rs - Tools crate · 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 · Archived subsystem maps and surface snapshots used as the parity baseline.
src/reference_data/subsystems/assistant.json - Surface snapshot · Archived high-level surface snapshot for comparison with the current workspace.
src/reference_data/archive_surface_snapshot.json - Parity tests · Workspace checks focused on porting and reference alignment.
tests/test_porting_workspace.py - API tests · Integration coverage for provider clients and streaming behavior.
rust/crates/api/tests/client_integration.rs - CLI 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 · Repository validation workflow for Rust build and test automation.
.github/workflows/rust-ci.yml
Connections 22
- 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.