Back to Details

claw-code-harness

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claw Code Harness

Claw Code Harness

Skill by 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.
由ara.so开发的Skill — 属于2026年度Skill合集。
Claw Code是Claude Code Agent Harness的干净实现Python重写版本（Rust移植版本正在开发中）。它提供了用于检查移植清单、枚举子系统、对照归档源进行一致性审计、查询工具/命令清单的能力，所有功能都可以通过CLI入口点调用，也可作为Python模块导入使用。

Installation

安装

bash
undefined
bash
undefined

Clone the repository

Clone the repository

git clone https://github.com/instructkr/claw-code.git cd claw-code
git clone https://github.com/instructkr/claw-code.git cd claw-code

Install dependencies (standard library only for core; extras for dev)

Install dependencies (standard library only for core; extras for dev)

pip install -r requirements.txt # if present, else no external deps required
pip install -r requirements.txt # if present, else no external deps required

Verify the workspace

Verify the workspace

python3 -m unittest discover -s tests -v

No PyPI package yet — use directly from source.

---
python3 -m unittest discover -s tests -v

目前还没有发布PyPI包，请直接从源码安装使用。

---

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
.
├── 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

CLI参考

All commands are invoked via 
python3 -m src.main <command>
.
所有命令都通过 
python3 -m src.main <command>
调用。

summary

summary

Render the full Python porting summary.
bash
python3 -m src.main summary
生成完整的Python移植进展汇总。
bash
python3 -m src.main summary

manifest

manifest

Print the current Python workspace manifest (file surface + subsystem names).
bash
python3 -m src.main manifest
打印当前Python工作区清单（文件范围+子系统名称）。
bash
python3 -m src.main manifest

subsystems

subsystems

List known subsystems, with optional limit.
bash
python3 -m src.main subsystems
python3 -m src.main subsystems --limit 16
列出已知子系统，支持可选的数量限制参数。
bash
python3 -m src.main subsystems
python3 -m src.main subsystems --limit 16

commands

commands

Inspect mirrored command inventory.
bash
python3 -m src.main commands
python3 -m src.main commands --limit 10
查看已同步的命令清单。
bash
python3 -m src.main commands
python3 -m src.main commands --limit 10

tools

tools

Inspect mirrored tool inventory.
bash
python3 -m src.main tools
python3 -m src.main tools --limit 10
查看已同步的工具清单。
bash
python3 -m src.main tools
python3 -m src.main tools --limit 10

parity-audit

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).
对照本地存在的（已加入gitignore的）归档快照运行一致性审计。
bash
python3 -m src.main parity-audit
需要本地归档文件存在于预期路径（不会被Git追踪）。

Core Modules & API

核心模块与API

src/models.py
— Dataclasses

src/models.py
— 数据类

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

A subsystem groups related modules

A subsystem groups related modules

sub = Subsystem(name="tool-harness", modules=[], status="in-progress")
sub = Subsystem(name="tool-harness", modules=[], status="in-progress")

A module represents a single ported file

A module represents a single ported file

mod = Module(name="tools.py", ported=True, notes="tool metadata only")
mod = Module(name="tools.py", ported=True, notes="tool metadata only")

BacklogState tracks overall port progress

BacklogState tracks overall port progress

state = BacklogState( total_subsystems=8, ported=5, backlog=3, notes="runtime slices pending" )
undefined
state = BacklogState( total_subsystems=8, ported=5, backlog=3, notes="runtime slices pending" )
undefined

src/tools.py
— Tool Port Metadata

src/tools.py
— 工具移植元数据

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)
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

src/commands.py
— 命令移植元数据

python
from src.commands import get_commands, CommandMeta

commands: list[CommandMeta] = get_commands()
for c in commands[:5]:
    print(c.name, c.ported)
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

src/query_engine.py
— 移植汇总渲染器

python
from src.query_engine import render_summary

summary_text: str = render_summary()
print(summary_text)
python
from src.query_engine import render_summary

summary_text: str = render_summary()
print(summary_text)

src/port_manifest.py
— Manifest Access

src/port_manifest.py
— 清单访问模块

python
from src.port_manifest import get_manifest, ManifestEntry

entries: list[ManifestEntry] = get_manifest()
for entry in entries:
    print(entry.path, entry.status)
python
from src.port_manifest import get_manifest, ManifestEntry

entries: list[ManifestEntry] = get_manifest()
for entry in entries:
    print(entry.path, entry.status)

Common Patterns

常用使用模式

Pattern 1: Check how many tools are ported

模式1：统计已完成移植的工具数量

python
from src.tools import get_tools

tools = get_tools()
ported = [t for t in tools if t.ported]
print(f"{len(ported)}/{len(tools)} tools ported")
python
from src.tools import get_tools

tools = get_tools()
ported = [t for t in tools if t.ported]
print(f"{len(ported)}/{len(tools)} tools ported")

Pattern 2: Find unported subsystems

模式2：查找未移植的子系统

python
from src.port_manifest import get_manifest

backlog = [e for e in get_manifest() if e.status != "ported"]
for entry in backlog:
    print(f"BACKLOG: {entry.path}")
python
from src.port_manifest import get_manifest

backlog = [e for e in get_manifest() if e.status != "ported"]
for entry in backlog:
    print(f"BACKLOG: {entry.path}")

Pattern 3: Programmatic summary pipeline

模式3：程序化生成汇总流水线

python
from src.query_engine import render_summary
from src.commands import get_commands
from src.tools import get_tools

print("=== Summary ===")
print(render_summary())

print("\n=== Commands ===")
for c in get_commands(limit=5):
    print(f"  {c.name}: ported={c.ported}")

print("\n=== Tools ===")
for t in get_tools(limit=5):
    print(f"  {t.name}: ported={t.ported}")
python
from src.query_engine import render_summary
from src.commands import get_commands
from src.tools import get_tools

print("=== Summary ===")
print(render_summary())

print("\n=== Commands ===")
for c in get_commands(limit=5):
    print(f"  {c.name}: ported={c.ported}")

print("\n=== Tools ===")
for t in get_tools(limit=5):
    print(f"  {t.name}: ported={t.ported}")

Pattern 4: Run tests before contributing

模式4：贡献代码前运行测试

bash
python3 -m unittest discover -s tests -v
bash
python3 -m unittest discover -s tests -v

Pattern 5: Using as part of an OmX/agent workflow

模式5：在OmX/Agent工作流中使用

bash
undefined
bash
undefined

Generate summary artifact for an agent to consume

Generate summary artifact for an agent to consume

python3 -m src.main summary > /tmp/claw_summary.txt
python3 -m src.main summary > /tmp/claw_summary.txt

Feed into another agent tool or diff against previous checkpoint

Feed into another agent tool or diff against previous checkpoint

diff /tmp/claw_summary_prev.txt /tmp/claw_summary.txt

---
diff /tmp/claw_summary_prev.txt /tmp/claw_summary.txt

---

Rust Port (In Progress)

Rust移植（开发中）

The Rust rewrite is on the 
dev/rust
 branch.
bash
undefined
Rust重写版本在
dev/rust
分支上开发。
bash
undefined

Switch to the Rust branch

Switch to the Rust branch

git fetch origin dev/rust git checkout dev/rust
git fetch origin dev/rust git checkout dev/rust

Build (requires Rust toolchain: https://rustup.rs)

Build (requires Rust toolchain: https://rustup.rs)

cargo build
cargo build

Run

Run

cargo run -- summary

> The Rust port aims for a faster, memory-safe harness runtime. It is **not yet merged** into main. Until then, use the Python implementation for all production workflows.

---
cargo run -- summary

> Rust版本的目标是提供更快、内存安全的Harness运行时。目前**尚未合并**到主分支。在此之前，所有生产工作流请使用Python实现版本。

---

Troubleshooting

故障排查

ProblemCauseFix
ModuleNotFoundError: No module named 'src'
Running from wrong directory
cd
to repo root, then 
python3 -m src.main ...
parity-audit
exits with "archive not found"		Local snapshot not presentPlace the archive at the expected local path (see 
port_manifest.py
for the path constant)
Tests fail with import errorsMissing 
__init__.py
Ensure 
src/__init__.py
exists; re-clone if needed
--limit
flag not recognized		Old checkout
git pull origin main
Rust build failsToolchain not installedRun 
curl https://sh.rustup.rs -sSf | sh
then retry
问题原因解决方法
ModuleNotFoundError: No module named 'src'
运行命令的目录错误切换到仓库根目录，再运行 
python3 -m src.main ...
parity-audit
退出并提示"archive not found"		本地不存在快照文件将归档文件放到预期的本地路径（路径常量可查看 
port_manifest.py
）
测试运行失败并提示导入错误缺少 
__init__.py
文件		确保 
src/__init__.py
存在，必要时重新克隆仓库
--limit
标志无法识别		本地代码版本过旧执行 
git pull origin main
拉取最新代码
Rust构建失败未安装Rust工具链运行 
curl https://sh.rustup.rs -sSf | sh
安装后重试

Key Design Notes for AI Agents

给AI Agent的核心设计说明

  • No external runtime dependencies for the core Python modules — safe to run in sandboxed environments.
  • query_engine.py
     is the single aggregation point — prefer it over calling individual modules when you need a full picture.
  • models.py
    dataclasses     are the canonical data shapes; always import types from there, not inline dicts.
  • parity-audit
    is read-only     — it does not modify any tracked files.
  • The project is not affiliated with Anthropic and contains no proprietary Claude Code source.
  • 核心Python模块无外部运行时依赖 — 可安全在沙箱环境中运行。
  • query_engine.py
     是唯一的聚合入口 — 当你需要获取完整信息时，优先使用它而不是调用单独的模块。
  • models.py
    中的数据类    是官方定义的数据结构；请始终从这里导入类型，不要使用内联字典。
  • parity-audit
    是只读的     — 不会修改任何被追踪的文件。
  • 本项目与Anthropic无关联，不包含任何Claude Code的专有源码。