How instructkr/claw-code works
1. This repo has two distinct layers
- The Python tree under src/ is the current porting/analysis workspace.
- The Rust workspace under rust/ is the executable systems-language implementation of the harness.
- Architecturally, the Python side is mostly metadata, parity tracking, and reporting, while the Rust side contains the runtime, CLI, integrations, and provider clients.
2. Python src/ is a porting control plane, not the main runtime
- Key modules like port_manifest.py, query_engine.py, commands.py, tools.py, and models.py describe and summarize the workspace.
- main.py exposes commands such as summary, manifest, subsystem listing, commands/tools inventories, and parity audit.
- This layer reads local reference data and produces high-level views of the project structure for verification and migration tracking.
3. Reference data is the Python side’s main input
- src/reference_data/ contains snapshots for subsystems, commands, tools, and archive surfaces.
- These snapshots are used to compare the current Python workspace against the archived/expected surface area.
- The tests/ directory validates this porting workspace rather than exercising the full agent runtime.
4. Rust is the main productized architecture
- The Rust workspace is split into focused crates: api, runtime, tools, commands, plugins, claw-cli, server, lsp, compat-harness, and compat-harness.
- This is a layered design: interface entrypoints at the top, runtime orchestration in the middle, and provider/tool/plugin integrations at the edges.
5. crates/claw-cli is the primary user-facing entrypoint
- It provides the interactive CLI, argument parsing, input handling, rendering, and project bootstrap/init flows.
- In the diagram, this is the main human-facing boundary: user input enters here, then flows into runtime/session orchestration.
6. crates/runtime is the orchestration core
- This crate owns session state, conversation history, compaction, prompt construction, permissions, sandboxing, file operations, hooks, config, usage accounting, and remote/MCP integration.
- It is the central hub where user intent, model responses, tool execution, and policy checks converge.
- Most other runtime-facing crates either feed data into it or are invoked by it.
7. Model/provider communication lives in crates/api
- The API crate abstracts model providers and streaming responses.
- It includes provider implementations for a Claw-specific provider and an OpenAI-compatible path, plus OAuth and SSE/streaming support.
- This is the external network boundary where the harness talks to model endpoints and receives incremental output.
8. Tooling and command execution are separate subsystems
- crates/tools defines tool manifests and execution framework.
- crates/commands handles slash commands, skills discovery, and config inspection.
- These are invoked by the runtime as part of agent action handling, and they form the bridge between language-model output and actual side effects.
9. Plugins and hooks extend behavior
- crates/plugins provides the plugin model and hook pipeline, with bundled example plugins.
- Hooks are an explicit extension boundary: runtime events can trigger pre/post behaviors without embedding those behaviors directly into core orchestration.
- This is a clear seam for customization and policy enforcement.
10. There are two additional integration surfaces besides the CLI
- crates/server provides an HTTP/SSE-style server boundary for remote or programmatic access.
- crates/lsp integrates with editor workflows through an LSP client/manager.
- crates/compat-harness exists as a compatibility layer for upstream editor or harness expectations.
11. MCP, OAuth, remote, and sandboxing are important external boundaries
- The runtime includes MCP client/stdio support, remote execution plumbing, OAuth, and sandbox components.
- These are the boundaries where the harness interacts with external tools, local environment constraints, or authenticated services.
- For an architecture diagram, these should be drawn as off-core dependencies connected to the runtime.
12. The typical runtime data flow is:
- user enters via CLI / server / LSP
- runtime loads session/config/permissions
- prompt is built and sent through API providers
- streamed model output comes back
- runtime may invoke commands, tools, MCP, hooks, plugins, file ops, or sandboxed actions
- results are folded back into conversation/session state and usage tracking.
13. The repository also includes verification and parity tooling
- Rust CI lives under rust/.github/workflows.
- Python verification is lightweight and centered on the porting workspace.
- The presence of snapshots and parity audit tooling indicates that architectural fidelity is a first-class concern, not just functionality.
14. How to draw it
- Put the Rust runtime in the center.
- Put CLI / server / LSP on the ingress side.
- Put API providers on the egress side.
- Attach tools, commands, plugins, hooks, MCP, sandbox, OAuth, remote around the runtime as extension and integration boundaries.
- Treat the Python src/ tree as a separate analysis/parity subsystem that observes and summarizes the architecture rather than executing the harness itself.
Main entry points: src/lib.rs Runtime core · file_ops.rs Execution boundary · src/lib.rs LSP · main.py Port CLI
Components 22
Python porting workspace
Analysis, parity tracking, and surface-area reporting for the ported workspace.
- Port CLI · Top-level commands for summaries, manifests, inventories, and parity audits.
src/main.py - Manifest · Describes the ported workspace surface and how it is tracked.
src/port_manifest.py - Query engine · Queries the local workspace and reference snapshots to build reports.
src/query_engine.py - Surface views · Command and tool summaries plus structured workspace views.
src/commands.py - Models · Shared Python-side structures for workspace, parity, and reporting data.
src/models.py - Snapshots · Archived subsystems, commands, tools, and surface snapshots used for comparison.
src/reference_data - Parity audit · Checks the current porting workspace against expected reference surfaces.
src/parity_audit.py - Port tests · Validates the Python porting workspace and snapshot-driven expectations.
tests/test_porting_workspace.py
Rust product workspace
Executable harness implementation and runtime orchestration.
- CLI · Human-facing command line boundary for input, rendering, and bootstrap flows.
rust/crates/claw-cli/src/main.rs - Runtime core · Coordinates sessions, conversation flow, policies, tools, and execution.
rust/crates/runtime/src/lib.rs - Session state · Owns session lifecycle, conversation history, and compaction.
rust/crates/runtime/src/session.rs - Prompt/policy · Builds prompts and applies permissions, config, and policy boundaries.
rust/crates/runtime/src/prompt.rs - Execution boundary · File ops, sandboxing, remote/MCP, OAuth, and other action boundaries.
rust/crates/runtime/src/file_ops.rs - Usage tracking · Tracks usage, usage-related state, and response accounting.
rust/crates/runtime/src/usage.rs - API layer · Streaming model provider abstraction and external endpoint integration.
rust/crates/api/src/lib.rs - Providers · Concrete provider implementations and compatibility paths for model calls.
rust/crates/api/src/providers/mod.rs - Tools · Defines tool manifests and execution framework used by the runtime.
rust/crates/tools/src/lib.rs - Commands · Handles slash commands, skills discovery, and config inspection.
rust/crates/commands/src/lib.rs - Plugins · Plugin model and hook pipeline for bundled and external extensions.
rust/crates/plugins/src/lib.rs
Integration surfaces
External entrypoints and extension boundaries around the runtime.
- Server · HTTP/SSE-style boundary for programmatic or remote access.
rust/crates/server/src/lib.rs - LSP · Editor workflow integration through an LSP client/manager.
rust/crates/lsp/src/lib.rs - Compat harness · Compatibility layer for upstream editor or harness expectations.
rust/crates/compat-harness/src/lib.rs
Connections 22
- Port CLI → Manifest: builds · Creates summaries and manifests from the workspace.
- Port CLI → Query engine: uses · Runs workspace queries for inventories and audits.
- Query engine → Snapshots: compares · Compares current state with stored snapshots.
- Parity audit → Snapshots: checks · Uses reference snapshots for parity validation.
- Surface views → Models: formats · Turns structured workspace data into reports.
- Port tests → Parity audit: validates · Exercises parity and porting expectations.
- CLI → Runtime core: enters · Primary user-facing input flows into runtime orchestration.
- Server → Runtime core: enters · Remote requests are handled by the runtime.
- LSP → Runtime core: enters · Editor-driven workflows feed into the runtime.
- Runtime core → Session state: manages · Owns session lifecycle and conversation state.
- Runtime core → Prompt/policy: builds · Constructs prompts and applies policy constraints.
- Runtime core → Execution boundary: dispatches · Invokes execution, file, sandbox, remote, and auth boundaries.
- Runtime core → Usage tracking: tracks · Records usage and accounting information.
- Runtime core → API layer: calls · Sends prompts and receives streamed model output.
- API layer → Providers: selects · Routes requests to provider-specific implementations.
- Runtime core → Tools: invokes · Executes agent tools as part of action handling.
- Runtime core → Commands: executes · Resolves slash commands and command-side workflows.
- Runtime core → Plugins: extends · Triggers hooks and plugin behaviors around runtime events.
- Plugins → Runtime core: hooks · Plugin hooks can observe or modify runtime events.
- Execution boundary → Server: integrates · Remote-oriented execution paths connect to programmatic access.
- Execution boundary → LSP: integrates · Editor-facing runtime actions connect through LSP workflows.
- Compat harness → LSP: adapts · Compatibility layer supports upstream/editor expectations.