Claw Code Harness

# Claw Code Harness

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Claw Code is a clean-room Python (with Rust port in progress) rewrite of the Claude Code agent harness. It provides tooling to inspect the port manifest, enumerate subsystems, audit parity against an archived source, and query tool/command inventories — all via a CLI entrypoint and importable Python modules.

---

## Installation

```bash
# Clone the repository
git clone https://github.com/instructkr/claw-code.git
cd claw-code

# Install dependencies (standard library only for core; extras for dev)
pip install -r requirements.txt  # if present, else no external deps required

# Verify the workspace
python3 -m unittest discover -s tests -v
```

No PyPI package yet — use directly from source.

---

## Repository Layout

```
.
├── src/
│   ├── __init__.py
│   ├── commands.py       # Python-side command port metadata
│   ├── main.py           # CLI entrypoint
│   ├── models.py         # Dataclasses: Subsystem, Module, BacklogState
│   ├── port_manifest.py  # Current Python workspace structure summary
│   ├── query_engine.py   # Renders porting summary from active workspace
│   ├── task.py           # Task primitives
│   └── tools.py          # Python-side tool port metadata
└── tests/                # Unittest suite
```

---

## CLI Reference

All commands are invoked via `python3 -m src.main <command>`.

### `summary`
Render the full Python porting summary.
```bash
python3 -m src.main summary
```

### `manifest`
Print the current Python workspace manifest (file surface + subsystem names).
```bash
python3 -m src.main manifest
```

### `subsystems`
List known subsystems, with optional limit.
```bash
python3 -m src.main subsystems
python3 -m src.main subsystems --limit 16
```

### `commands`
Inspect mirrored command inventory.
```bash
python3 -m src.main commands
python3 -m src.main commands --limit 10
```

### `tools`
Inspect mirrored tool inventory.
```bash
python3 -m src.main tools
python3 -m src.main tools --limit 10
```

### `parity-audit`
Run parity audit against a locally present (gitignored) archived snapshot.
```bash
python3 -m src.main parity-audit
```
> Requires the local archive to be present at its expected path (not tracked in git).

---

## Core Modules & API

### `src/models.py` — Dataclasses

```python
from src.models import Subsystem, Module, BacklogState

# A subsystem groups related modules
sub = Subsystem(name="tool-harness", modules=[], status="in-progress")

# A module represents a single ported file
mod = Module(name="tools.py", ported=True, notes="tool metadata only")

# BacklogState tracks overall port progress
state = BacklogState(
    total_subsystems=8,
    ported=5,
    backlog=3,
    notes="runtime slices pending"
)
```

### `src/tools.py` — Tool Port Metadata

```python
from src.tools import get_tools, ToolMeta

tools: list[ToolMeta] = get_tools()
for t in tools[:5]:
    print(t.name, t.ported, t.description)
```

### `src/commands.py` — Command Port Metadata

```python
from src.commands import get_commands, CommandMeta

commands: list[CommandMeta] = get_commands()
for c in commands[:5]:
    print(c.name, c.ported)
```

### `src/query_engine.py` — Porting Summary Renderer

```python
from src.query_engine import render_summary

summary_text: str = render_summary()
print(summary_text)
```

### `src/port_manifest.py` — Manifest Access

```python
from src.port_manifest import get_manifest, ManifestEntry