# ashik-manjunath/claw-code architecture

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

- Interactive diagram: https://gitdiagram.com/ashik-manjunath/claw-code
- Repository: https://github.com/ashik-manjunath/claw-code

## Overview

#### Purpose and Entry Points
This is a clean-room, dual-language rewrite workspace for an AI agent harness. The active Python surface primarily reports porting/parity metadata; the Rust workspace is the substantive CLI/runtime port. Python commands enter through `src/main.py`; the Rust interactive binary enters through `rust/crates/claw-cli/src/main.rs` and application wiring in `rust/crates/claw-cli/src/app.rs`.

#### Python Porting Workspace
Python models the intended system surface and renders inventories rather than providing full runtime equivalence. `src/port_manifest.py` assembles the workspace representation, `src/models.py` defines subsystem/module/backlog data, and `src/query_engine.py` produces summaries. CLI dispatch in `src/main.py` exposes manifest, subsystem, command/tool inventory, and parity-audit operations.

#### Rust CLI Interaction Layer
The Rust CLI owns interactive user control flow: argument parsing, initialization/bootstrap, input collection, and output rendering. Its boundary is a terminal REPL/application frontend over runtime and API crates. Key paths: `rust/crates/claw-cli/src/main.rs`, `rust/crates/claw-cli/src/args.rs`, `rust/crates/claw-cli/src/render.rs`.

#### Agent Runtime and Session Orchestration
The runtime crate is the central harness layer: it manages sessions and conversations, constructs prompts, compacts context, applies permissions/sandboxing, and coordinates tool-oriented execution. It is also the integration boundary for MCP, remote behavior, OAuth, SSE, filesystem operations, and usage tracking. Key paths: `rust/crates/runtime/src/lib.rs`, `rust/crates/runtime/src/session.rs`, `rust/crates/runtime/src/mcp.rs`.

#### Model Provider and Streaming Boundary
The API crate abstracts LLM providers behind shared client/types/error interfaces. It supports a native Claw provider and OpenAI-compatible endpoints, with streaming/SSE transport. Runtime/CLI should depend on this abstraction rather than provider-specific protocols. Key paths: `rust/crates/api/src/client.rs`, `rust/crates/api/src/providers/openai_compat.rs`, `rust/crates/api/src/sse.rs`.

#### Extensibility, Tools, and Commands
Tool definitions/execution, slash-command behavior, skills/config inspection, and plugins/hooks are separated into dedicated crates. Plugins can supply lifecycle hooks and bundled plugin packages; this is the primary extension boundary around the core runtime. Key paths: `rust/crates/tools/src/lib.rs`, `rust/crates/commands/src/lib.rs`, `rust/crates/plugins/src/hooks.rs`.

#### Editor and Server Integrations
The workspace includes an LSP client/manager for editor-facing integration, a compatibility harness for upstream-editor behavior, and a server crate described as HTTP/SSE-based. These are adapters around the core runtime rather than alternate runtimes. Key paths: `rust/crates/lsp/src/manager.rs`, `rust/crates/compat-harness/src/lib.rs`, `rust/crates/server/src/lib.rs`.

#### Build and External Dependencies
Rust is a Cargo workspace rooted at `rust/Cargo.toml`, with CI under `rust/.github/workflows/ci.yml`. Material external interfaces are LLM provider APIs (including OpenAI-compatible APIs), OAuth authentication, Server-Sent Events, MCP servers over stdio, shell/file operations, and LSP/editor clients. Python verification is limited to the porting workspace under `tests/test_porting_workspace.py`.

Main entry points: [`rust/crates/runtime/src/lib.rs`](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/runtime/src/lib.rs) (Agent Runtime), [`rust/crates/api/src/client.rs`](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/api/src/client.rs) (Provider API Abstraction), [`rust/crates/claw-cli/src/main.rs`](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/claw-cli/src/main.rs) (Rust CLI Entry), [`src/port_manifest.py`](https://github.com/ashik-manjunath/claw-code/blob/main/src/port_manifest.py) (Port Manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python Porting Workspace"]
  node_py_main["Python CLI<br/>entrypoint<br/>[main.py]"]
  node_py_manifest["Port Manifest<br/>workspace model<br/>[port_manifest.py]"]
  node_py_models["Porting Models<br/>data model<br/>[models.py]"]
  node_py_query["Summary Queries<br/>query layer<br/>[query_engine.py]"]
end

subgraph group_cli["Rust CLI"]
  node_rust_cli_main["Rust CLI Entry<br/>binary entrypoint<br/>[main.rs]"]
  node_cli_args["Argument Parsing<br/>CLI input<br/>[args.rs]"]
  node_cli_render["Terminal Rendering<br/>CLI output<br/>[render.rs]"]
end

subgraph group_core["Rust Runtime Core"]
  node_runtime{{"Agent Runtime<br/>orchestration<br/>[lib.rs]"}}
  node_sessions["Sessions &amp; Conversations<br/>runtime state<br/>[session.rs]"]
  node_mcp["MCP Integration<br/>runtime adapter<br/>[mcp.rs]"]
  node_api_client{{"Provider API Abstraction<br/>LLM client<br/>[client.rs]"}}
  node_openai_compat["OpenAI-Compatible Provider<br/>provider adapter<br/>[openai_compat.rs]"]
  node_sse["SSE Streaming<br/>transport<br/>[sse.rs]"]
end

subgraph group_extensions["Extensions"]
  node_tools["Tools<br/>execution extension<br/>[lib.rs]"]
  node_commands["Slash Commands<br/>command extension<br/>[lib.rs]"]
  node_plugins["Plugin Hooks<br/>extension boundary<br/>[hooks.rs]"]
end

subgraph group_adapters["Integration Adapters"]
  node_lsp["LSP Manager<br/>editor adapter<br/>[manager.rs]"]
  node_compat["Compatibility Harness<br/>upstream adapter<br/>[lib.rs]"]
  node_server["HTTP/SSE Server<br/>server adapter<br/>[lib.rs]"]
end

node_providers(("LLM Provider APIs<br/>external service"))
node_mcp_servers(("MCP Servers<br/>external process"))
node_editor(("Editor Clients<br/>external client"))

node_py_main -->|"renders"| node_py_manifest
node_py_manifest -->|"uses"| node_py_models
node_py_main -->|"queries"| node_py_query
node_py_query -->|"summarizes"| node_py_manifest
node_rust_cli_main -->|"parses"| node_cli_args
node_rust_cli_main -->|"boots and drives"| node_runtime
node_rust_cli_main -->|"renders through"| node_cli_render
node_runtime -->|"manages"| node_sessions
node_runtime -->|"requests models via"| node_api_client
node_runtime -->|"coordinates"| node_mcp
node_runtime -->|"executes"| node_tools
node_runtime -->|"applies"| node_commands
node_runtime -->|"invokes hooks"| node_plugins
node_api_client -->|"implements"| node_openai_compat
node_api_client -->|"streams with"| node_sse
node_api_client -->|"calls"| node_providers
node_mcp -->|"stdio"| node_mcp_servers
node_lsp -->|"adapts"| node_runtime
node_server -->|"serves"| node_runtime
node_compat -.->|"exercises"| node_runtime
node_editor -->|"connects to"| node_lsp

click node_py_main "https://github.com/ashik-manjunath/claw-code/blob/main/src/main.py"
click node_py_manifest "https://github.com/ashik-manjunath/claw-code/blob/main/src/port_manifest.py"
click node_py_models "https://github.com/ashik-manjunath/claw-code/blob/main/src/models.py"
click node_py_query "https://github.com/ashik-manjunath/claw-code/blob/main/src/query_engine.py"
click node_rust_cli_main "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/claw-cli/src/main.rs"
click node_cli_args "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/claw-cli/src/args.rs"
click node_cli_render "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/claw-cli/src/render.rs"
click node_runtime "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/runtime/src/lib.rs"
click node_sessions "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/runtime/src/session.rs"
click node_mcp "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/runtime/src/mcp.rs"
click node_api_client "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/api/src/client.rs"
click node_openai_compat "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/api/src/providers/openai_compat.rs"
click node_sse "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/api/src/sse.rs"
click node_tools "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/tools/src/lib.rs"
click node_commands "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/commands/src/lib.rs"
click node_plugins "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/plugins/src/hooks.rs"
click node_lsp "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/lsp/src/manager.rs"
click node_compat "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/compat-harness/src/lib.rs"
click node_server "https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/server/src/lib.rs"

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_manifest,node_py_models,node_py_query toneBlue
class node_rust_cli_main,node_cli_args,node_cli_render toneAmber
class node_runtime,node_sessions,node_mcp,node_api_client,node_openai_compat,node_sse toneMint
class node_tools,node_commands,node_plugins toneRose
class node_lsp,node_compat,node_server toneIndigo
class node_providers,node_mcp_servers,node_editor toneNeutral
```

## Components

### Python Porting Workspace

Metadata and parity reporting surface.

- [Python CLI](https://github.com/ashik-manjunath/claw-code/blob/main/src/main.py): entrypoint · Dispatches inventory and parity-audit commands. · `src/main.py`
- [Port Manifest](https://github.com/ashik-manjunath/claw-code/blob/main/src/port_manifest.py): workspace model · Assembles the intended port representation. · `src/port_manifest.py`
- [Porting Models](https://github.com/ashik-manjunath/claw-code/blob/main/src/models.py): data model · Defines subsystem, module, and backlog metadata. · `src/models.py`
- [Summary Queries](https://github.com/ashik-manjunath/claw-code/blob/main/src/query_engine.py): query layer · Produces workspace summaries. · `src/query_engine.py`

### Rust CLI

Interactive terminal frontend.

- [Rust CLI Entry](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/claw-cli/src/main.rs): binary entrypoint · Starts the interactive application. · `rust/crates/claw-cli/src/main.rs`
- [Argument Parsing](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/claw-cli/src/args.rs): CLI input · `rust/crates/claw-cli/src/args.rs`
- [Terminal Rendering](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/claw-cli/src/render.rs): CLI output · `rust/crates/claw-cli/src/render.rs`

### Rust Runtime Core

Session orchestration and provider boundary.

- [Agent Runtime](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/runtime/src/lib.rs): orchestration · Owns sessions, prompts, context, permissions, and tool execution. · `rust/crates/runtime/src/lib.rs`
- [Sessions & Conversations](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/runtime/src/session.rs): runtime state · `rust/crates/runtime/src/session.rs`
- [MCP Integration](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/runtime/src/mcp.rs): runtime adapter · Connects MCP servers over stdio. · `rust/crates/runtime/src/mcp.rs`
- [Provider API Abstraction](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/api/src/client.rs): LLM client · Shared provider clients, types, and errors. · `rust/crates/api/src/client.rs`
- [OpenAI-Compatible Provider](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/api/src/providers/openai_compat.rs): provider adapter · `rust/crates/api/src/providers/openai_compat.rs`
- [SSE Streaming](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/api/src/sse.rs): transport · `rust/crates/api/src/sse.rs`

### Extensions

Tools, commands, and plugin hooks.

- [Tools](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/tools/src/lib.rs): execution extension · Defines and executes agent tools. · `rust/crates/tools/src/lib.rs`
- [Slash Commands](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/commands/src/lib.rs): command extension · `rust/crates/commands/src/lib.rs`
- [Plugin Hooks](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/plugins/src/hooks.rs): extension boundary · Lifecycle hooks and bundled plugin packages. · `rust/crates/plugins/src/hooks.rs`

### Integration Adapters

Editor, compatibility, and server-facing adapters.

- [LSP Manager](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/lsp/src/manager.rs): editor adapter · `rust/crates/lsp/src/manager.rs`
- [Compatibility Harness](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/compat-harness/src/lib.rs): upstream adapter · Validates upstream-editor behavior. · `rust/crates/compat-harness/src/lib.rs`
- [HTTP/SSE Server](https://github.com/ashik-manjunath/claw-code/blob/main/rust/crates/server/src/lib.rs): server adapter · `rust/crates/server/src/lib.rs`

### Other components

- **LLM Provider APIs**: external service · Native Claw and OpenAI-compatible endpoints.
- **MCP Servers**: external process · Stdio-connected tool servers.
- **Editor Clients**: external client

## Connections

- Python CLI → Port Manifest: renders
- Port Manifest → Porting Models: uses
- Python CLI → Summary Queries: queries
- Summary Queries → Port Manifest: summarizes
- Rust CLI Entry → Argument Parsing: parses
- Rust CLI Entry → Agent Runtime: boots and drives
- Rust CLI Entry → Terminal Rendering: renders through
- Agent Runtime → Sessions & Conversations: manages
- Agent Runtime → Provider API Abstraction: requests models via
- Agent Runtime → MCP Integration: coordinates
- Agent Runtime → Tools: executes
- Agent Runtime → Slash Commands: applies
- Agent Runtime → Plugin Hooks: invokes hooks
- Provider API Abstraction → OpenAI-Compatible Provider: implements
- Provider API Abstraction → SSE Streaming: streams with
- Provider API Abstraction → LLM Provider APIs: calls
- MCP Integration → MCP Servers: stdio
- LSP Manager → Agent Runtime: adapts
- HTTP/SSE Server → Agent Runtime: serves
- Compatibility Harness → Agent Runtime: exercises
- Editor Clients → LSP Manager: connects to