How selvin-paul-raj/claw-code works
1. Overall shape
- This repo is a dual-language project, but the Rust workspace under rust/ is the canonical product surface: it builds the claw CLI agent harness.
- The top-level src/ tree is a Python/reference workspace used for parity auditing, subsystem snapshots, and migration helpers; it is not the primary runtime.
2. Primary runtime boundary
- The Rust workspace is organized as a set of crates that separate:
- the CLI shell,
- the agent/runtime orchestration layer,
- the API/provider layer,
- and supporting subsystems like plugins, telemetry, tools, and mocks.
- This gives a clean boundary between user-facing commands, execution policy, and external model/provider communication.
3. CLI entrypoint
- rust/crates/rusty-claude-cli is the executable front door.
- It handles command-line parsing, interactive input/rendering, and startup behavior, then delegates into the runtime and command crates.
- The top-level README points users to claw doctor, login, prompt, and session workflows, so the CLI is the main user interaction layer.
4. Runtime orchestration layer
- rust/crates/runtime is the core control plane for agent execution.
- It contains modules for configuration, session state, prompts, permissions, sandboxing, hooks, MCP integration, git/worktree context, branch/session control, and recovery/summary logic.
- This crate is the main boundary where input from the CLI becomes an orchestrated agent session with policy, filesystem, and process control.
5. Model/API boundary
- rust/crates/api isolates all provider-facing concerns.
- It includes HTTP client behavior, streaming/SSE handling, prompt caching, error types, and provider adapters for Anthropic and OpenAI-compatible endpoints.
- Architecture-wise, this is the only layer that should know how to talk to remote model APIs; the runtime consumes it rather than embedding provider details directly.
6. Tools and capability execution
- rust/crates/tools contains reusable operational tools such as lane completion and PDF extraction.
- These are not the agent itself; they are capability modules that the runtime can invoke through its tool/task plumbing.
- In the broader architecture, tools sit between agent intent and concrete side effects.
7. Plugin and hook system
- rust/crates/plugins plus bundled examples define the plugin model and hook conventions.
- The runtime also has hook, lifecycle, and permission enforcement modules, which indicates that plugins are executed through a constrained lifecycle rather than directly.
- This creates a clear extension boundary: plugins can augment behavior, but the runtime still controls execution, trust, and policy.
8. MCP and remote integration
- The runtime contains multiple MCP-related modules (mcp, mcp_client, mcp_server, mcp_stdio, mcp_tool_bridge, lifecycle hardening).
- That suggests the agent can expose or consume tools over the Model Context Protocol and bridge those into the internal tool system.
- This is a key integration boundary: internal task execution can be extended by remote or external tool servers.
9. Auth, trust, permissions, and sandboxing
- The runtime includes OAuth, trust resolution, permission enforcement, policy engine, sandboxing, and branch-locking modules.
- These form the safety boundary around agent actions: before a task can mutate files, invoke commands, or access resources, the runtime decides whether it is allowed and under what constraints.
- If you are drawing the architecture, this should be shown as a governance layer wrapping execution.
10. Session, conversation, and persistence
- The runtime has dedicated modules for sessions, conversation management, transcripts, history, task registry, task packets, usage, and summary compression.
- This indicates the system preserves state across interactive turns and likely serializes session data for resume/recovery workflows.
- The CLI consumes this state to support session resumption and compacted histories.
11. Testing, parity, and mock infrastructure
- The repo invests heavily in parity validation: rust/compat-harness, rust/mock-anthropic-service, rust/mock_parity_scenarios.json, and the parity-harness scripts.
- This is reinforced by the top-level Python helpers such as src/parity_audit.py, src/reference_data/, and tests/test_porting_workspace.py.
- Architecturally, there is a deliberate split between the production runtime and a deterministic test/migration harness used to compare behavior against reference implementations.
12. Repository operations and delivery
- CI is Rust-focused (.github/workflows/rust-ci.yml) with a release pipeline and a doc/source-of-truth checker.
- Container support is first-class via Containerfile and docs/container.md, which suggests reproducible builds and containerized workflows are part of the deployment story.
- install.sh, USAGE.md, and rust/README.md are operational docs rather than code, but they describe the intended lifecycle: build, authenticate, run, test, and validate parity.
13. How to read the architecture at a glance
- Data flow is: user command in CLI → runtime orchestration → policy/sandbox/session layers → API/provider or tool/MCP execution → streamed output back to CLI.
- Side channels include plugins/hooks, git/worktree context, and telemetry/usage.
- The Python tree and mock harnesses exist primarily to audit, compare, and preserve behavior during the Rust port rather than to power the main runtime.
Main entry points: src/lib.rs Runtime core · src/lib.rs Parity harness · main.rs CLI shell · src/lib.rs Provider API
Components 19
Rust product
Primary CLI agent runtime and supporting crates under rust/
- CLI shell · Executable front door for commands, prompts, interactive input, and output rendering.
rust/crates/rusty-claude-cli/src/main.rs - Input · Command parsing and interactive input handling.
rust/crates/rusty-claude-cli/src/input.rs - Render · Terminal rendering and presentation of streamed responses and status.
rust/crates/rusty-claude-cli/src/render.rs - Startup · Initial CLI setup, defaults, and startup behavior before delegating to runtime.
rust/crates/rusty-claude-cli/src/init.rs - Runtime core · Session orchestration, policy, filesystem/process control, and agent execution boundaries.
rust/crates/runtime/src/lib.rs - Sessions · Conversation state, task registry, transcripts, summaries, and resume/recovery flows.
rust/crates/runtime/src/session.rs - Policy · Permissions, trust resolution, policy enforcement, sandboxing, and branch locking.
rust/crates/runtime/src/policy_engine.rs - Integrations · MCP, remote execution, hooks, plugin lifecycle, and OAuth-style connectivity.
rust/crates/runtime/src/mcp.rs - Context · Git/worktree state, prompts, config, bootstrap, and execution context management.
rust/crates/runtime/src/git_context.rs - Provider API · HTTP clients, streaming, prompt caching, errors, and provider adapters for model endpoints.
rust/crates/api/src/lib.rs - Providers · Anthropic and OpenAI-compatible provider implementations.
rust/crates/api/src/providers/mod.rs - Transport · HTTP client behavior and streaming/SSE handling for provider communication.
rust/crates/api/src/http_client.rs - Tools · Reusable operational capabilities invoked by the runtime, such as lane completion and PDF extraction.
rust/crates/tools/src/lib.rs - Plugins · Plugin model, hook conventions, and bundled examples for constrained augmentation.
rust/crates/plugins/src/lib.rs - Telemetry · Usage and telemetry support for observing agent activity.
rust/crates/telemetry/src/lib.rs
Python reference
Parity, migration, and reference workspace under src/
- Python tree · Python reference implementation used for parity auditing, subsystem snapshots, and migration helpers.
src/main.py - Parity audit · Audit and reference-data tooling that compares subsystems and behavior against snapshots.
src/parity_audit.py
Validation and delivery
CI, parity harnesses, containerization, and release support
- Parity harness · Mock services and compatibility harnesses for deterministic comparison and migration checks.
rust/crates/compat-harness/src/lib.rs - CI & release · Workflow, release, documentation checks, and containerized build delivery.
.github/workflows/rust-ci.yml
Connections 21
- CLI shell → Input: parse · CLI parses commands and interactive input.
- CLI shell → Render: render · CLI presents output and streamed responses.
- CLI shell → Startup: bootstrap · CLI initializes defaults and startup state.
- CLI shell → Runtime core: delegate · User-facing commands hand off to the runtime control plane.
- Runtime core → Sessions: manage · Runtime maintains sessions, tasks, transcripts, and recovery state.
- Runtime core → Policy: enforce · Runtime wraps execution in permissions, trust, and sandbox policy.
- Runtime core → Integrations: bridge · Runtime reaches MCP, plugins, hooks, OAuth, and remote integrations.
- Runtime core → Context: context · Runtime builds execution context from config, git, prompts, and bootstrap data.
- Runtime core → Provider API: call · Runtime sends model/provider requests through the API boundary.
- Runtime core → Tools: invoke · Runtime can execute reusable tools as capabilities.
- Runtime core → Telemetry: emit · Runtime records usage and telemetry signals.
- Provider API → Transport: transport · API layer handles HTTP and streaming mechanics.
- Provider API → Providers: adapt · API exposes provider-specific adapters behind one boundary.
- Integrations → Plugins: load · Plugins are loaded and constrained through lifecycle and hooks.
- Integrations → Parity harness: exercise · Integration and parity harnesses validate external behaviors.
- Python tree → Parity audit: audit · Python reference workspace supports parity and subsystem snapshots.
- Parity harness → Provider API: mock · Mock services stand in for provider communication during parity tests.
- Parity harness → Runtime core: compare · Harnesses compare runtime behavior against reference scenarios.
- Parity audit → Parity harness: check · Audit tooling feeds and inspects deterministic harness outputs.
- CI & release → Parity harness: validate · CI and release flows run parity and compatibility checks.
- CI & release → Python tree: verify · Operational checks include source-of-truth and reference validation.