eeymoo/claw-code
1
0
Fork 0
mirror of https://github.com/instructkr/claw-code.git synced 2026-04-07 00:24:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

Refresh docs to match ultraworkers/claw-code source of truth

Browse Source 
Replace the stale Python-first README narrative, old community links, and leftover branded metadata with the current Rust-first repo guidance. Also align funding handles and asset naming so the public docs point at the canonical ultraworkers/claw-code surface.\n\nConstraint: Scope limited to docs/metadata and branding residue; no runtime behavior changes\nRejected: Add a new CI lint in this pass | outside the requested docs-and-config cleanup scope\nConfidence: medium\nScope-risk: narrow\nReversibility: clean\nDirective: Keep README, funding metadata, and community links aligned with ultraworkers/claw-code and the current UltraWorkers Discord invite\nTested: stale-branding grep across markdown/.github; root doc-link existence checks; cargo fmt --all --check; cargo check --workspace; cargo test --workspace\nNot-tested: cargo clippy --workspace --all-targets -- -D warnings | fails on pre-existing runtime lint debt unrelated to these doc changes
This commit is contained in:
Yeachan-Heo
2026-04-05 17:26:41 +00:00
parent de758a52dd
commit 55d9f1da56
5 changed files with 60 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
README.md
View File

@@ -1,7 +1,17 @@
# Rewriting Project Claw Code
# Claw Code
<p align="center">
<strong>⭐ The fastest repo in history to surpass 50K stars, reaching the milestone in just 2 hours after publication ⭐</strong>
<a href="https://github.com/ultraworkers/claw-code">ultraworkers/claw-code</a>
·
<a href="./USAGE.md">Usage</a>
·
<a href="./rust/README.md">Rust workspace</a>
·
<a href="./PARITY.md">Parity</a>
·
<a href="./ROADMAP.md">Roadmap</a>
·
<a href="https://discord.gg/5TUQKqFWd">UltraWorkers Discord</a>
</p>
<p align="center">
@@ -9,193 +19,75 @@
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date" width="600" />
<img alt="Star history for ultraworkers/claw-code" src="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date" width="600" />
</picture>
</a>
</p>
<p align="center">
<img src="assets/clawd-hero.jpeg" alt="Claw" width="300" />
<img src="assets/claw-hero.jpeg" alt="Claw Code" width="300" />
</p>
<p align="center">
<strong>Autonomously maintained by lobsters/claws — not by human hands</strong>
</p>
<p align="center">
<a href="https://github.com/Yeachan-Heo/clawhip">clawhip</a> ·
<a href="https://github.com/code-yeongyu/oh-my-openagent">oh-my-openagent</a> ·
<a href="https://github.com/Yeachan-Heo/oh-my-claudecode">oh-my-claudecode</a> ·
<a href="https://github.com/Yeachan-Heo/oh-my-codex">oh-my-codex</a> ·
<a href="https://discord.gg/6ztZB9jvWq">UltraWorkers Discord</a>
</p>
Claw Code is the public Rust implementation of the `claw` CLI agent harness.
The canonical implementation lives in [`rust/`](./rust), and the current source of truth for this repository is **ultraworkers/claw-code**.
> [!IMPORTANT]
> The active Rust workspace now lives in [`rust/`](./rust). Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows, make the doctor health check your first run, use [`rust/README.md`](./rust/README.md) for crate-level details, and see [`docs/container.md`](./docs/container.md) for Docker/Podman container-first usage.
> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Use [`rust/README.md`](./rust/README.md) for crate-level details and [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint.
> Want the bigger idea behind this repo? Read [`PHILOSOPHY.md`](./PHILOSOPHY.md) and Sigrid Jin's public explanation: https://x.com/realsigridjin/status/2039472968624185713
## Current repository shape
> Shout-out to the UltraWorkers ecosystem powering this repo: [clawhip](https://github.com/Yeachan-Heo/clawhip), [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent), [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex), and the [UltraWorkers Discord](https://discord.gg/6ztZB9jvWq).
- **`rust/`** — canonical Rust workspace and the `claw` CLI binary
- **`USAGE.md`** — task-oriented usage guide for the current product surface
- **`PARITY.md`** — Rust-port parity status and migration notes
- **`ROADMAP.md`** — active roadmap and cleanup backlog
- **`PHILOSOPHY.md`** — project intent and system-design framing
- **`src/` + `tests/`** — companion Python/reference workspace and audit helpers; not the primary runtime surface
---
## Backstory
This repo is maintained by **lobsters/claws**, not by a conventional human-only dev team.
The people behind the system are [Bellman / Yeachan Heo](https://github.com/Yeachan-Heo) and friends like [Yeongyu](https://github.com/code-yeongyu), but the repo itself is being pushed forward by autonomous claw workflows: parallel coding sessions, event-driven orchestration, recovery loops, and machine-readable lane state.
In practice, that means this project is not just *about* coding agents — it is being **actively built by them**. Features, tests, telemetry, docs, and workflow hardening are landed through claw-driven loops using [clawhip](https://github.com/Yeachan-Heo/clawhip), [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent), [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), and [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex).
This repository exists to prove that an open coding harness can be built **autonomously, in public, and at high velocity** — with humans setting direction and claws doing the grinding.
See the public build story here:
https://x.com/realsigridjin/status/2039472968624185713
![Tweet screenshot](assets/tweet-screenshot.png)
---
## New user onboarding
If you are here to try the Rust CLI, make the doctor check the first thing you run after building:
## Quick start
```bash
cd rust
cargo build --workspace
./target/debug/claw
# first command inside the REPL
/doctor
./target/debug/claw --help
./target/debug/claw prompt "summarize this repository"
```
`/doctor` is the built-in setup and preflight diagnostic. After your first session, you can rerun the same health check with `./target/debug/claw --resume latest /doctor`.
For the rest of the install, auth, session, and parity-harness workflow, continue in [`USAGE.md`](./USAGE.md).
## Porting Status
The main source tree is now Python-first.
- `src/` contains the active Python porting workspace
- `tests/` verifies the current Python workspace
- the exposed snapshot is no longer part of the tracked repository state
The current Python workspace is not yet a complete one-to-one replacement for the original system, but the primary implementation surface is now Python.
## Why this rewrite exists
I originally studied the exposed codebase to understand its harness, tool wiring, and agent workflow. After spending more time with the legal and ethical questions—and after reading the essay linked below—I did not want the exposed snapshot itself to remain the main tracked source tree.
This repository now focuses on Python porting work instead.
## Repository Layout
```text
.
├── src/ # Python porting workspace
│ ├── __init__.py
│ ├── commands.py
│ ├── main.py
│ ├── models.py
│ ├── port_manifest.py
│ ├── query_engine.py
│ ├── task.py
│ └── tools.py
├── tests/ # Python verification
├── assets/omx/ # OmX workflow screenshots
├── 2026-03-09-is-legal-the-same-as-legitimate-ai-reimplementation-and-the-erosion-of-copyleft.md
└── README.md
```
## Python Workspace Overview
The new Python `src/` tree currently provides:
- **`port_manifest.py`** — summarizes the current Python workspace structure
- **`models.py`** — dataclasses for subsystems, modules, and backlog state
- **`commands.py`** — Python-side command port metadata
- **`tools.py`** — Python-side tool port metadata
- **`query_engine.py`** — renders a Python porting summary from the active workspace
- **`main.py`** — a CLI entrypoint for manifest and summary output
## Python workspace quickstart
Render the Python porting summary:
Authenticate with either an API key or the built-in OAuth flow:
```bash
python3 -m src.main summary
export ANTHROPIC_API_KEY="sk-ant-..."
# or
cd rust
./target/debug/claw login
```
Print the current Python workspace manifest:
Run the workspace test suite:
```bash
python3 -m src.main manifest
cd rust
cargo test --workspace
```
List the current Python modules:
## Documentation map
```bash
python3 -m src.main subsystems --limit 16
```
- [`USAGE.md`](./USAGE.md) — quick commands, auth, sessions, config, parity harness
- [`rust/README.md`](./rust/README.md) — crate map, CLI surface, features, workspace layout
- [`PARITY.md`](./PARITY.md) — parity status for the Rust port
- [`rust/MOCK_PARITY_HARNESS.md`](./rust/MOCK_PARITY_HARNESS.md) — deterministic mock-service harness details
- [`ROADMAP.md`](./ROADMAP.md) — active roadmap and open cleanup work
- [`PHILOSOPHY.md`](./PHILOSOPHY.md) — why the project exists and how it is operated
Run verification:
## Ecosystem
```bash
python3 -m unittest discover -s tests -v
```
Claw Code is built in the open alongside the broader UltraWorkers toolchain:
Run the parity audit against the local ignored archive (when present):
- [clawhip](https://github.com/Yeachan-Heo/clawhip)
- [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent)
- [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
- [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- [UltraWorkers Discord](https://discord.gg/5TUQKqFWd)
```bash
python3 -m src.main parity-audit
```
Inspect mirrored command/tool inventories:
```bash
python3 -m src.main commands --limit 10
python3 -m src.main tools --limit 10
```
## Current Parity Checkpoint
The port now mirrors the archived root-entry file surface, top-level subsystem names, and command/tool inventories much more closely than before. However, it is **not yet** a full runtime-equivalent replacement for the original TypeScript system; the Python tree still contains fewer executable runtime slices than the archived source.
## Built with `oh-my-codex`
The restructuring and documentation work on this repository was AI-assisted and orchestrated with Yeachan Heo's [oh-my-codex (OmX)](https://github.com/Yeachan-Heo/oh-my-codex), layered on top of Codex.
- **`$team` mode:** used for coordinated parallel review and architectural feedback
- **`$ralph` mode:** used for persistent execution, verification, and completion discipline
- **Codex-driven workflow:** used to turn the main `src/` tree into a Python-first porting workspace
### OmX workflow screenshots
![OmX workflow screenshot 1](assets/omx/omx-readme-review-1.png)
*Ralph/team orchestration view while the README and essay context were being reviewed in terminal panes.*
![OmX workflow screenshot 2](assets/omx/omx-readme-review-2.png)
*Split-pane review and verification flow during the final README wording pass.*
## Community
<p align="center">
<a href="https://discord.gg/6ztZB9jvWq"><img src="https://img.shields.io/badge/UltraWorkers-Discord-5865F2?logo=discord&style=for-the-badge" alt="UltraWorkers Discord" /></a>
</p>
Join the [**UltraWorkers Discord**](https://discord.gg/6ztZB9jvWq) — the community around clawhip, oh-my-openagent, oh-my-claudecode, oh-my-codex, and claw-code. Come chat about LLMs, harness engineering, agent workflows, and autonomous software development.
[![Discord](https://img.shields.io/badge/Join%20Discord-UltraWorkers-5865F2?logo=discord&style=for-the-badge)](https://discord.gg/6ztZB9jvWq)
## Star History
See the chart at the top of this README.
## Ownership / Affiliation Disclaimer
## Ownership / affiliation disclaimer
- This repository does **not** claim ownership of the original Claude Code source material.
- This repository is **not affiliated with, endorsed by, or maintained by Anthropic**.