How ultraworkers/claw-code-parity works
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: runtime Runtime · query_engine.py Query engine · rusty-claude-cli Rust CLI · reference_data Reference data
Components 19
Python porting plane
Manifesting, snapshot lookup, and parity auditing around mirrored subsystem metadata.
- Main CLI · Lightweight command entrypoint for manifesting and query flows.
src/main.py - Query engine · Resolves repository structure and powers subsystem or command queries.
src/query_engine.py - Port manifest · Builds workspace summaries and porting inventories from known structure.
src/port_manifest.py - Parity audit · Compares current workspace structure against archived snapshots.
src/parity_audit.py - Reference data · Archived subsystem and tool snapshots used as the structural source of truth.
src/reference_data - Assistant · Representative mirrored subsystem boundary from the ported Python tree.
src/assistant - Server · 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 · User-facing executable that parses input, renders output, and boots the app.
rust/crates/rusty-claude-cli - Args · Argument and flag handling for the Rust front end.
rust/crates/rusty-claude-cli/src/args.rs - Input · Interactive input and prompt handling at the CLI boundary.
rust/crates/rusty-claude-cli/src/input.rs - Render · Terminal rendering and presentation for the executable UI.
rust/crates/rusty-claude-cli/src/render.rs - Runtime · Central execution layer for sessions, permissions, sandboxing, hooks, and task flow.
rust/crates/runtime - API · Model-provider integration layer with streaming, caching, and typed request/response models.
rust/crates/api - Tools · Shared tool surface used by runtime-adjacent execution and integrations.
rust/crates/tools - Plugins · Plugin and hook package with bundled lifecycle hook examples.
rust/crates/plugins - Telemetry · Support crate for runtime observability and tracking.
rust/crates/telemetry - Mock service · Local Anthropic-compatible service used for tests and parity runs.
rust/crates/mock-anthropic-service - Compat harness · Compatibility harness for replaying scenarios and checking behavioral parity.
rust/crates/compat-harness - Commands · Shared command surface used by the Rust workspace.
rust/crates/commands
Connections 20
- 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.