# ashwin-magalu/claw-code architecture

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

- Interactive diagram: https://gitdiagram.com/ashwin-magalu/claw-code
- Repository: https://github.com/ashwin-magalu/claw-code

## Overview

This repository is primarily a Python porting workspace, not yet a runtime-equivalent agent harness. Its main workflow is to invoke the CLI, assemble a workspace manifest, and produce summaries or other views of mirrored commands, tools, and runtime behavior. The Python runtime models routing and turns, while query/session modules provide turn output and persistence. The README also identifies parity auditing and inventory views as workspace capabilities. Rust crates are present as an in-progress port, but the available documentation centers the active Python workspace; unsampled Python subsystems are shown only where the CLI or source index supports them.

Main entry points: [`src/main.py`](https://github.com/ashwin-magalu/claw-code/blob/main/src/main.py) (Python CLI), [`src/query_engine.py`](https://github.com/ashwin-magalu/claw-code/blob/main/src/query_engine.py) (Query engine), [`src/runtime.py`](https://github.com/ashwin-magalu/claw-code/blob/main/src/runtime.py) (Port runtime), [`src/tools.py`](https://github.com/ashwin-magalu/claw-code/blob/main/src/tools.py) (Tool inventory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and reporting"]
  node_cli["Python CLI<br/>[main.py]"]
end

subgraph group_inventory["Port inventory"]
  node_manifest["Port manifest<br/>[port_manifest.py]"]
  node_models["Port models<br/>[models.py]"]
  node_commands["Command inventory<br/>[commands.py]"]
  node_tools["Tool inventory<br/>[tools.py]"]
  node_permissions["Tool permissions<br/>[permissions.py]"]
end

subgraph group_runtime["Mirrored runtime"]
  node_engine["Query engine<br/>[query_engine.py]"]
  node_runtime_loop["Port runtime<br/>[runtime.py]"]
  node_context["Runtime context<br/>[context.py]"]
end

subgraph group_workspace["Workspace state"]
  node_history["Turn history<br/>[history.py]"]
  node_session[("Session store<br/>[session_store.py]")]
  node_transcript[("Transcript store<br/>[transcript.py]")]
  node_setup["Setup report<br/>[setup.py]"]
  node_audit["Parity audit<br/>[parity_audit.py]"]
end

node_user(("CLI user"))

node_user -->|"invokes"| node_cli
node_cli -->|"builds"| node_manifest
node_cli -->|"renders summary"| node_engine
node_cli -->|"runs turns"| node_runtime_loop
node_cli -->|"lists commands"| node_commands
node_cli -->|"lists tools"| node_tools
node_cli -->|"configures permissions"| node_permissions
node_cli -->|"runs audit"| node_audit
node_cli -->|"reports setup"| node_setup
node_engine -->|"builds workspace view"| node_manifest
node_engine -->|"loads backlog"| node_commands
node_engine -->|"loads backlog"| node_tools
node_engine -->|"uses data types"| node_models
node_engine -->|"loads and saves"| node_session
node_engine -->|"records turns"| node_transcript
node_runtime_loop -->|"runs turn engine"| node_engine
node_runtime_loop -->|"routes commands"| node_commands
node_runtime_loop -->|"routes tools"| node_tools
node_runtime_loop -->|"builds context"| node_context
node_runtime_loop -->|"records events"| node_history
node_tools -->|"filters tools"| node_permissions

click node_cli "https://github.com/ashwin-magalu/claw-code/blob/main/src/main.py"
click node_manifest "https://github.com/ashwin-magalu/claw-code/blob/main/src/port_manifest.py"
click node_models "https://github.com/ashwin-magalu/claw-code/blob/main/src/models.py"
click node_commands "https://github.com/ashwin-magalu/claw-code/blob/main/src/commands.py"
click node_tools "https://github.com/ashwin-magalu/claw-code/blob/main/src/tools.py"
click node_permissions "https://github.com/ashwin-magalu/claw-code/blob/main/src/permissions.py"
click node_engine "https://github.com/ashwin-magalu/claw-code/blob/main/src/query_engine.py"
click node_runtime_loop "https://github.com/ashwin-magalu/claw-code/blob/main/src/runtime.py"
click node_context "https://github.com/ashwin-magalu/claw-code/blob/main/src/context.py"
click node_history "https://github.com/ashwin-magalu/claw-code/blob/main/src/history.py"
click node_session "https://github.com/ashwin-magalu/claw-code/blob/main/src/session_store.py"
click node_transcript "https://github.com/ashwin-magalu/claw-code/blob/main/src/transcript.py"
click node_setup "https://github.com/ashwin-magalu/claw-code/blob/main/src/setup.py"
click node_audit "https://github.com/ashwin-magalu/claw-code/blob/main/src/parity_audit.py"

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_cli,node_user toneBlue
class node_manifest,node_models,node_commands,node_tools,node_permissions toneAmber
class node_engine,node_runtime_loop,node_context toneMint
class node_history,node_session,node_transcript,node_setup,node_audit toneRose
```

## Components

### CLI and reporting

- [Python CLI](https://github.com/ashwin-magalu/claw-code/blob/main/src/main.py): `src/main.py`

### Port inventory

- [Port manifest](https://github.com/ashwin-magalu/claw-code/blob/main/src/port_manifest.py): `src/port_manifest.py`
- [Port models](https://github.com/ashwin-magalu/claw-code/blob/main/src/models.py): `src/models.py`
- [Command inventory](https://github.com/ashwin-magalu/claw-code/blob/main/src/commands.py): `src/commands.py`
- [Tool inventory](https://github.com/ashwin-magalu/claw-code/blob/main/src/tools.py): `src/tools.py`
- [Tool permissions](https://github.com/ashwin-magalu/claw-code/blob/main/src/permissions.py): `src/permissions.py`

### Mirrored runtime

- [Query engine](https://github.com/ashwin-magalu/claw-code/blob/main/src/query_engine.py): `src/query_engine.py`
- [Port runtime](https://github.com/ashwin-magalu/claw-code/blob/main/src/runtime.py): `src/runtime.py`
- [Runtime context](https://github.com/ashwin-magalu/claw-code/blob/main/src/context.py): `src/context.py`

### Workspace state

- [Turn history](https://github.com/ashwin-magalu/claw-code/blob/main/src/history.py): `src/history.py`
- [Session store](https://github.com/ashwin-magalu/claw-code/blob/main/src/session_store.py): `src/session_store.py`
- [Transcript store](https://github.com/ashwin-magalu/claw-code/blob/main/src/transcript.py): `src/transcript.py`
- [Setup report](https://github.com/ashwin-magalu/claw-code/blob/main/src/setup.py): `src/setup.py`
- [Parity audit](https://github.com/ashwin-magalu/claw-code/blob/main/src/parity_audit.py): `src/parity_audit.py`

### Other components

- **CLI user**

## Connections

- CLI user → Python CLI: invokes (evidence: `README.md`)
- Python CLI → Port manifest: builds (evidence: `src/main.py`)
- Python CLI → Query engine: renders summary (evidence: `src/main.py`)
- Python CLI → Port runtime: runs turns (evidence: `src/main.py`)
- Python CLI → Command inventory: lists commands (evidence: `src/main.py`)
- Python CLI → Tool inventory: lists tools (evidence: `src/main.py`)
- Python CLI → Tool permissions: configures permissions (evidence: `src/main.py`)
- Python CLI → Parity audit: runs audit (evidence: `src/main.py`)
- Python CLI → Setup report: reports setup (evidence: `src/main.py`)
- Query engine → Port manifest: builds workspace view (evidence: `src/query_engine.py`)
- Query engine → Command inventory: loads backlog (evidence: `src/query_engine.py`)
- Query engine → Tool inventory: loads backlog (evidence: `src/query_engine.py`)
- Query engine → Port models: uses data types (evidence: `src/query_engine.py`)
- Query engine → Session store: loads and saves (evidence: `src/query_engine.py`)
- Query engine → Transcript store: records turns (evidence: `src/query_engine.py`)
- Port runtime → Query engine: runs turn engine (evidence: `src/runtime.py`)
- Port runtime → Command inventory: routes commands (evidence: `src/runtime.py`)
- Port runtime → Tool inventory: routes tools (evidence: `src/runtime.py`)
- Port runtime → Runtime context: builds context (evidence: `src/runtime.py`)
- Port runtime → Turn history: records events (evidence: `src/runtime.py`)
- Tool inventory → Tool permissions: filters tools (evidence: `src/tools.py`)