From 2a8b41411d0a135038a6ec22d184f5b1b26bc884 Mon Sep 17 00:00:00 2001 From: icakinser <129708616+icakinser@users.noreply.github.com> Date: Thu, 14 May 2026 01:16:02 -0400 Subject: [PATCH] Convert README to HTML format Replace README content with HTML structure and styling. --- README.md | 802 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 592 insertions(+), 210 deletions(-) diff --git a/README.md b/README.md index 0b0900778a..d0db98ecfb 100644 --- a/README.md +++ b/README.md @@ -1,210 +1,592 @@ -# Claw Code - -

- ultraworkers/claw-code - · - Usage - · - Rust workspace - · - Parity - · - Roadmap - · - UltraWorkers Discord -

- -

- - - - - Star history for ultraworkers/claw-code - - -

- -

- Claw Code -

- -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] -> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Make `claw doctor` your first health check after building, use [`rust/README.md`](./rust/README.md) for crate-level details, read [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint, and see [`docs/container.md`](./docs/container.md) for the container-first workflow. -> -> **ACP / Zed status:** `claw-code` does not ship an ACP/Zed daemon entrypoint yet. Run `claw acp` (or `claw --acp`) for the current status instead of guessing from source layout; `claw acp serve` is currently a discoverability alias only, and real ACP support remains tracked separately in `ROADMAP.md`. - -## Current repository shape - -- **`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 - -## Quick start - -> [!NOTE] -> [!WARNING] -> **`cargo install claw-code` installs the wrong thing.** The `claw-code` crate on crates.io is a deprecated stub that places `claw-code-deprecated.exe` — not `claw`. Running it only prints `"claw-code has been renamed to agent-code"`. **Do not use `cargo install claw-code`.** Either build from source (this repo) or install the upstream binary: -> ```bash -> cargo install agent-code # upstream binary — installs 'agent.exe' (Windows) / 'agent' (Unix), NOT 'agent-code' -> ``` -> This repo (`ultraworkers/claw-code`) is **build-from-source only** — follow the steps below. - -```bash -# 1. Clone and build -git clone https://github.com/ultraworkers/claw-code -cd claw-code/rust -cargo build --workspace - -# 2. Set your API key (Anthropic API key — not a Claude subscription) -export ANTHROPIC_API_KEY="sk-ant-..." - -# 3. Verify everything is wired correctly -./target/debug/claw doctor - -# 4. Run a prompt -./target/debug/claw prompt "say hello" -``` - -> [!NOTE] -> **Windows (PowerShell):** the binary is `claw.exe`, not `claw`. Use `.\target\debug\claw.exe` or run `cargo run -- prompt "say hello"` to skip the path lookup. - -### Windows setup - -**PowerShell is a supported Windows path.** Use whichever shell works for you. The common onboarding issues on Windows are: - -1. **Install Rust first** — download from and run the installer. Close and reopen your terminal when it finishes. -2. **Verify Rust is on PATH:** - ```powershell - cargo --version - ``` - If this fails, reopen your terminal or run the PATH setup from the Rust installer output, then retry. -3. **Clone and build** (works in PowerShell, Git Bash, or WSL): - ```powershell - git clone https://github.com/ultraworkers/claw-code - cd claw-code/rust - cargo build --workspace - ``` -4. **Run** (PowerShell — note `.exe` and backslash): - ```powershell - $env:ANTHROPIC_API_KEY = "sk-ant-..." - .\target\debug\claw.exe prompt "say hello" - ``` - -**Git Bash / WSL** are optional alternatives, not requirements. If you prefer bash-style paths (`/c/Users/you/...` instead of `C:\Users\you\...`), Git Bash (ships with Git for Windows) works well. In Git Bash, the `MINGW64` prompt is expected and normal — not a broken install. - -## Post-build: locate the binary and verify - -After running `cargo build --workspace`, the `claw` binary is built but **not** automatically installed to your system. Here's where to find it and how to verify the build succeeded. - -### Binary location - -After `cargo build --workspace` in `claw-code/rust/`: - -**Debug build (default, faster compile):** -- **macOS/Linux:** `rust/target/debug/claw` -- **Windows:** `rust/target/debug/claw.exe` - -**Release build (optimized, slower compile):** -- **macOS/Linux:** `rust/target/release/claw` -- **Windows:** `rust/target/release/claw.exe` - -If you ran `cargo build` without `--release`, the binary is in the `debug/` folder. - -### Verify the build succeeded - -Test the binary directly using its path: - -```bash -# macOS/Linux (debug build) -./rust/target/debug/claw --help -./rust/target/debug/claw doctor - -# Windows PowerShell (debug build) -.\rust\target\debug\claw.exe --help -.\rust\target\debug\claw.exe doctor -``` - -If these commands succeed, the build is working. `claw doctor` is your first health check — it validates your API key, model access, and tool configuration. - -### Optional: Add to PATH - -If you want to run `claw` from any directory without the full path, choose one of these approaches: - -**Option 1: Symlink (macOS/Linux)** -```bash -ln -s $(pwd)/rust/target/debug/claw /usr/local/bin/claw -``` -Then reload your shell and test: -```bash -claw --help -``` - -**Option 2: Use `cargo install` (all platforms)** - -Build and install to Cargo's default location (`~/.cargo/bin/`, which is usually on PATH): -```bash -# From the claw-code/rust/ directory -cargo install --path . --force - -# Then from anywhere -claw --help -``` - -**Option 3: Update shell profile (bash/zsh)** - -Add this line to `~/.bashrc` or `~/.zshrc`: -```bash -export PATH="$(pwd)/rust/target/debug:$PATH" -``` - -Reload your shell: -```bash -source ~/.bashrc # or source ~/.zshrc -claw --help -``` - -### Troubleshooting - -- **"command not found: claw"** — The binary is in `rust/target/debug/claw`, but it's not on your PATH. Use the full path `./rust/target/debug/claw` or symlink/install as above. -- **"permission denied"** — On macOS/Linux, you may need `chmod +x rust/target/debug/claw` if the executable bit isn't set (rare). -- **Debug vs. release** — If the build is slow, you're in debug mode (default). Add `--release` to `cargo build` for faster runtime, but the build itself will take 5–10 minutes. - -> [!NOTE] -> **Auth:** claw requires an **API key** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) — Claude subscription login is not a supported auth path. - -Run the workspace test suite after verifying the binary works: - -```bash -cd rust -cargo test --workspace -``` - -## Documentation map - -- [`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 - -## Ecosystem - -Claw Code is built in the open alongside the broader UltraWorkers toolchain: - -- [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) - -## 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**. + + + + + + Claw Code — Local Fork Overview + + + + + +
+
+
+ + Active Development Fork +
+

Claw Code Local

+

+ A hardened, feature-enriched fork of ultraworkers/claw-code + with real diffing, atomic file operations, local LLM support, and + a rigorous code-editing workflow board. +

+
+
+
5
+
Commits Ahead
+
+
+
21
+
User Stories Done
+
+
+
7/14
+
Milestones Complete
+
+
+
900+
+
Tests Passing
+
+
+
+
+ +
+
+

+ + Fork Comparison +

+

What changed between the upstream repo and this local fork.

+ +
+
+

+ + ultraworkers/claw-code + Upstream +

+

1,043 commits · 9-lane parity checkpoint · 40 tool specs

+
    +
  • Bash validation, CI fix, file-tool edge cases
    • +
  • TaskRegistry + Team/Cron registries (in-memory)
    • +
  • MCP lifecycle bridge + LSP client dispatch
    • +
  • Permission enforcement (read-only vs workspace-write)
    • +
  • Mock parity harness with 10 scripted scenarios
    • +
  • Basic edit_file with naive string replace
    • +
  • No diff engine — degenerate hunks on every edit
    • +
  • No atomic writes — direct fs::write calls
    • +
  • /undo registered but unimplemented (no-op)
    • +
  • No read-before-edit tracking
    • +
+
+ +
+

+ + claw-code-local (this fork) + +5 commits +

+

All upstream features + local LLM + hardened editing pipeline

+
    +
  • Embedded local LLM — llama.cpp provider with tool calling & streaming
    • +
  • Real diff engine — similar-powered structured patches & git-style unified diffs
    • +
  • Ambiguity guard — edit_file rejects non-unique matches unless replace_all=true
    • +
  • Atomic writes — temp-file + rename + fsync + permission preservation
    • +
  • Encoding fidelity — CRLF, BOM, and trailing-newline round-trip preservation
    • +
  • SHA tracker — read-before-edit enforcement & conflict detection
    • +
  • MultiEdit tool — atomic multi-hunk edits, all-or-nothing semantics
    • +
  • /undo works — per-session edit history, SHA-256 validation, --force override
    • +
  • Typed errors — structured TypedError envelopes across API + runtime + CLI
    • +
  • Model compatibility — Kimi, reasoning models, GPT-5, Qwen/DashScope fixes
    • +
+
+
+ +
+ git diff upstream/main..HEAD + + +19,328 lines added  ·  + -6,802 lines removed  ·  + 91 files changed + +
+
+
+ +
+
+

+ + Accomplishments +

+

Completed milestones and delivered user stories.

+ +
+
+
● Done
+

M1 — Real structuredPatch diff

+

Replaced degenerate hunks with real diffing via similar::TextDiff. Every edit now produces accurate oldStart/oldLines/newStart/newLines hunks and a populated gitDiff field.

+
diff.rs, file_ops.rs
+
+ +
+
● Done
+

M2 — edit_file uniqueness check

+

Ambiguous matches (2+ occurrences with replace_all=false) now return a typed EditError::Ambiguous instead of silently mutating the first hit.

+
file_ops.rs
+
+ +
+
● Done
+

M3 — Atomic write (tempfile + rename + fsync)

+

Crash-safe file edits via NamedTempFile, explicit sync_all, atomic persist, and Unix permission preservation. No more truncated files on power loss.

+
atomic_write.rs, file_ops.rs
+
+ +
+
● Done
+

M4 — CRLF / BOM / trailing-newline preservation

+

New text_encoding.rs detects FileShape (line ending, BOM, trailing newline), normalises to LF for the model, and restores the original shape on write.

+
text_encoding.rs
+
+ +
+
● Done
+

M5 — Read-before-edit tracking

+

FileTracker records SHA-256 + mtime on every read_file. Subsequent edits are denied if the file was never read or was modified externally since the read.

+
file_tracker.rs
+
+ +
+
● Done
+

M6 — MultiEdit tool

+

Atomic multi-hunk edits. Applies N sequential EditOps in-memory first; if any op fails, the file is never touched. One combined structuredPatch is returned on success.

+
tools/src/lib.rs, multi_edit.rs
+
+ +
+
● Done
+

M7 — /undo actually undoes

+

Per-session EditHistory stack (cap 50). /undo restores original bytes with SHA-256 validation. /undo --force skips the check. Stack cleared across sessions.

+
edit_history.rs, commands/src/lib.rs
+
+ +
+
● Done
+

M9 — SHA conflict detection

+

Optional expected_sha256 on EditFileInput / WriteFileInput. Mismatch yields EditError::Conflict with expected vs actual hashes, preventing stale overwrites.

+
tools/src/lib.rs, file_ops.rs
+
+ +
+
● Done
+

Local LLM Provider (llama.cpp)

+

Embedded llama.cpp backend with tool calling, streaming, and thinking-budget control for reasoning models. Includes nightly CI workflow and container support.

+
llama_cpp.rs, nightly-local-llama.yml
+
+ +
+
● Done
+

Typed Error Envelope Contract

+

TypedError with 9 kinds, structured fields (kind, operation, target, detail, hint, retryable), JSON + text rendering, and downcasting from ApiError / SessionControlError.

+
typed_error.rs, main.rs
+
+ +
+
● Done
+

Model Compatibility Hardening

+

Kimi is_error exclusion, reasoning-model tuning stripping, GPT-5 max_completion_tokens, Qwen/DashScope routing, and request-body size pre-flight checks.

+
openai_compat.rs, MODEL_COMPATIBILITY.md
+
+ +
+
● Done
+

Performance Benchmarks

+

Criterion benchmark suite for request-building hot paths. flatten_tool_result_content optimised with pre-allocated capacity — ~17 ns single-text, ~11.7 µs large-content.

+
benches/request_building.rs
+
+
+
+
+ +
+
+
+

What This Fork Demonstrates

+

+ Beyond the original 9-lane parity checkpoint, this fork proves that a small, + focused set of incremental milestones can transform a stub-heavy codebase into a + production-resilient editing harness — with real diffs, atomic safety, encoding fidelity, + and undo — all validated by 900+ tests and a deterministic mock parity harness. +

+ + View Upstream Repo + + +
+
+
+ + + + +