Onboarding: ultraworkers/claw-code

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Missing license — unclear to depend on

• Last commit today
• 3 active contributors
• CI configured
• Tests present
• ⚠ Small team — 3 top contributors
• ⚠ Concentrated ownership — top contributor handles 73% of commits
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

Claw Code is a Rust implementation of a CLI agent harness called claw, designed to drive AI coding agents (like Claude) from the command line. The canonical implementation lives in rust/ as a Cargo workspace, and it competes in the same space as tools like claude-code or agent-code. It provides session management, a parity harness for tracking Rust-port completeness, and a claw doctor health-check subcommand. The repo is a hybrid monorepo: rust/ is the canonical Cargo workspace (members = crates/*), housing all Rust crates and the claw binary; companion Python tooling and audit helpers live at the root in src/ and tests/. Documentation is split across USAGE.md, PARITY.md, ROADMAP.md, PHILOSOPHY.md, and docs/, while .claude/sessions/ stores AI agent session JSON blobs.

Who it's for

Rust developers and AI-tooling enthusiasts who want a self-hosted, build-from-source CLI agent harness — particularly those who want to run or extend a Claude-like coding agent without depending on the upstream agent-code binary, or who want to audit/contribute to the Rust port of that agent.

Maturity & risk

The repo claims to have surpassed 100K GitHub stars extremely quickly, suggesting viral growth rather than long-term organic maturity. CI is present via .github/workflows/rust-ci.yml and .github/workflows/release.yml, and the workspace enforces strict Clippy lints with unsafe_code = 'forbid'. However, the ROADMAP and PARITY docs explicitly acknowledge incomplete features (e.g., ACP/Zed support is stub-only), placing this firmly in the 'actively developed but not production-ready' category.

The cargo install claw-code path is explicitly broken — the crates.io stub installs a deprecated binary — so onboarding risk is high for anyone not reading the README carefully. The project is build-from-source only with publish = false in rust/Cargo.toml, meaning no versioned release artifacts. Single-maintainer risk is unclear, but the rapid star growth suggests community momentum that may not reflect contributor depth.

Active areas of work

Active work is focused on the Rust port parity checkpoint (tracked in PARITY.md), ACP/Zed daemon support (currently a discoverability stub via claw acp serve), and container-first deployment (documented in docs/container.md with a Containerfile present). The .claude/sessions/ directory shows numerous recent AI-assisted coding sessions, suggesting the repo itself is being built with claw.

Get running

git clone https://github.com/ultraworkers/claw-code.git cd claw-code/rust cargo build --release ./target/release/claw doctor

Daily commands: cd rust && cargo run -- doctor # health check cargo run -- --help # full CLI surface cargo run -- acp # check ACP/Zed status

Map of the codebase

• rust/Cargo.toml — Workspace manifest defining all crates, shared dependencies, and lint policies — the root of the entire Rust build graph.
• rust/crates/api/src/client.rs — Core API client abstraction that orchestrates request building, provider dispatch, and streaming — the central load-bearing module.
• rust/crates/api/src/providers/anthropic.rs — Anthropic-specific provider implementation; defines how requests are serialized and responses deserialized for the primary supported LLM.
• rust/crates/api/src/sse.rs — Server-Sent Events parsing layer that converts raw HTTP streams into structured token/event objects consumed by the client.
• rust/crates/api/src/types.rs — Shared type definitions (requests, responses, messages) used across all crates — changing these has cascading effects everywhere.
• rust/crates/api/src/providers/openai_compat.rs — OpenAI-compatible provider that enables non-Anthropic models; critical for understanding multi-provider support strategy.
• CLAUDE.md — Top-level contributor guide describing repo conventions, build commands, and the source-of-truth rule every contributor must follow.

How to make changes

Add a new LLM provider

1. Define a new module file implementing the Provider trait (request serialization, auth, response deserialization) (rust/crates/api/src/providers/my_provider.rs)
2. Register the new module and add it to the provider enum/match in the providers registry (rust/crates/api/src/providers/mod.rs)
3. Add any provider-specific request/response types or extend existing ones (rust/crates/api/src/types.rs)
4. Write integration tests exercising the new provider's happy path and error cases (rust/crates/api/tests/openai_compat_integration.rs)
5. Document model names and known quirks for the new provider (docs/MODEL_COMPATIBILITY.md)

Add a new streaming event type

1. Add the new variant to the StreamEvent enum and any associated data structs (rust/crates/api/src/types.rs)
2. Implement parsing logic for the new SSE event field/type in the SSE parser (rust/crates/api/src/sse.rs)
3. Update the client loop to handle and surface the new event variant to callers (rust/crates/api/src/client.rs)
4. Add integration test asserting the new event is emitted correctly end-to-end (rust/crates/api/tests/client_integration.rs)

Add a new top-level crate to the workspace

1. Create the new crate directory and Cargo.toml, referencing workspace.package fields (rust/crates/my_crate/Cargo.toml)
2. Register the new crate in the workspace members list (rust/Cargo.toml)
3. Add a lib.rs or main.rs with the crate's public surface (rust/crates/my_crate/src/lib.rs)
4. Reference the api crate as a path dependency if LLM calls are needed (rust/crates/my_crate/Cargo.toml)

Add prompt caching support for a new provider

1. Extend prompt cache header/annotation logic to handle the new provider's cache_control format (rust/crates/api/src/prompt_cache.rs)
2. Wire the cache control into the new provider's request builder (rust/crates/api/src/providers/my_provider.rs)
3. Expose any new cache configuration options through the shared type definitions (rust/crates/api/src/types.rs)

Why these technologies

• Rust — Memory safety without GC, zero-cost async, and predictable latency — critical for a CLI agent harness that streams LLM output with minimal overhead.
• Cargo workspaces — Splits api, and future crates (TUI, CLI binary, etc.) into independently testable units while sharing a single lock file and lint policy.
• Server-Sent Events (SSE) streaming — Anthropic and OpenAI APIs emit tokens incrementally via SSE; native async SSE parsing lets the CLI surface output with lowest possible latency.
• reqwest (async HTTP) — Mature, tokio-native HTTP client with streaming body support, widely used in the Rust ecosystem, reducing maintenance burden.
• serde / serde_json — De-facto standard for Rust JSON serialization; listed as a workspace dependency ensuring a single version across all crates.

Trade-offs already made

• Single api crate for all providers

  • Why: Keeps the dependency graph flat and avoids code duplication for shared types, HTTP logic, and SSE parsing.
  • Consequence: The api crate grows as providers are added; care is needed to avoid feature-flag explosion or tight coupling between providers.

• Forbid unsafe_code workspace-wide

  • Why: Maximises memory-safety guarantees and simplifies auditing for a security-sensitive CLI tool that handles API keys.
  • Consequence: Some low-level performance optimisations (e.g. custom allocators, SIMD parsing) are off the table without a targeted unsafe allow.

• Prompt caching as a first-class concern (prompt_cache.rs)

  • Why: Anthropic prompt caching can reduce cost and latency by >80% for repeated context; baking it in early avoids retrofit complexity.
  • Consequence: Adds annotation logic that must be kept in sync with Anthropic API changes; other providers may not support it, creating conditional paths.

• OpenAI-compat provider as a separate file from Anthropic

  • Why: The two APIs differ enough in auth, body schema, and streaming format that merging them would create a complex conditional mess.
  • Consequence: Some shared logic (retry, timeout, SSE parsing) may be duplicated or require careful abstraction through the provider trait.

Non-goals (don't propose these)

• Being a general-purpose HTTP client library — the api crate is sc

Traps & gotchas

Running cargo install claw-code installs a completely different, deprecated stub crate from crates.io that prints a rename message and exits — it does NOT install this repo's binary. The workspace has publish = false, so there are no crates.io releases from this repo. claw acp serve appears as a valid subcommand but is currently a discoverability alias only with no real ACP daemon behind it. The .claude/sessions/ JSON files are AI agent session artifacts committed to the repo — do not treat them as application config.

Architecture

Concepts to learn

• Agent Harness / Agent Loop — Claw is explicitly described as a 'CLI agent harness' — understanding the read-eval-act loop pattern for LLM agents is foundational to reading the codebase.
• Cargo Workspace — The entire Rust project is structured as a Cargo workspace (members = ['crates/*']) — knowing how workspace-level dependency resolution and lint inheritance works is essential for adding or modifying crates.
• ACP (Agent Communication Protocol) — Claw's roadmap explicitly tracks ACP/Zed daemon support; ACP is the inter-process protocol between editors like Zed and external agent processes.
• Clippy Lint Levels and Priority — The workspace Cargo.toml uses priority = -1 on all and pedantic lint groups with selective allows — understanding Clippy's lint level precedence is required to add code without breaking CI.
• OCI Containerfile (Podman-compatible) — The repo ships a Containerfile (not Dockerfile) for container-first deployment — Containerfiles are the Podman/Buildah-native format, a non-obvious distinction from Docker.
• Source of Truth Documentation Pattern — The repo enforces a single source-of-truth doc contract via .github/scripts/check_doc_source_of_truth.py in CI — understanding this pattern prevents doc drift PRs from being rejected unexpectedly.

Related repos

• anthropics/claude-code — The upstream CLI agent product that claw-code is porting to Rust — canonical reference for feature parity tracked in PARITY.md.
• continuedev/continue — Alternative open-source AI coding agent harness with IDE integration, competing in the same developer-agent tooling space.
• zed-industries/zed — The ACP/Zed daemon integration is an explicit roadmap item in this repo — Zed is the editor whose agent protocol claw aims to support.
• serde-rs/serde — serde_json is the only pinned workspace dependency; understanding Rust serialization is required for working with session JSON blobs.
• tokio-rs/tokio — Likely async runtime underpinning the CLI agent loop (standard for Rust CLI tools of this type), relevant for contributors working on async session handling.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for the Rust workspace crates covering session serialization/deserialization

The .claude/sessions/ and rust/.claude/sessions/ directories contain dozens of JSON session files, but there are no visible test files in the Rust workspace that validate the session data structures used by the claw engine. Given the workspace uses serde_json as a workspace dependency and has multiple crates under rust/crates/*, adding integration tests that round-trip session JSON (using the actual session files as fixtures) would catch regressions in the core data model and demonstrate correct serde derive usage across crate boundaries.

• [ ] Audit rust/crates/*/src/ for the session-related structs (likely in a session or store crate) that map to the JSON shape found in .claude/sessions/session-1774998936453.json and siblings.
• [ ] Create rust/crates/<session-crate>/tests/session_roundtrip.rs with #[test] cases that serde_json::from_str each fixture file from .claude/sessions/ and .claw/sessions/ and assert the result serializes back to semantically equivalent JSON.
• [ ] Add the fixture files (or a subset) under rust/crates/<session-crate>/tests/fixtures/ so tests are self-contained and runnable with cargo test.
• [ ] Ensure clippy and the workspace lint rules (pedantic, unsafe_code = forbid) pass on the new test module.
• [ ] Update CLAUDE.md with a note on how to run the new integration tests.

Add a cargo-deny / dependency audit GitHub Actions workflow to the existing CI pipeline

The repo already has .github/workflows/rust-ci.yml and .github/workflows/release.yml, but there is no workflow that checks for known CVEs, duplicate dependencies, or disallowed licenses in the Rust workspace. Given the project is built in Rust, ships a binary (install.sh), and has >100K stars making it a supply-chain target, adding a cargo-deny check is a high-value, low-effort hardening step that complements the existing rust-ci.yml.

• [ ] Create .github/workflows/security-audit.yml that triggers on push to main and on pull_request, running cargo deny check against the rust/ workspace.
• [ ] Add a deny.toml (or rust/deny.toml) configuration file specifying: [licenses] allowing only MIT/Apache-2.0/ISC (consistent with workspace.package.license = "MIT"), [bans] blocking duplicate versions of serde_json, and [advisories] using the RustSec database.
• [ ] Pin the EmbarkStudios/cargo-deny-action version in the workflow for reproducibility.
• [ ] Verify the workflow passes locally with cargo deny --manifest-path rust/Cargo.toml check before opening the PR.
• [ ] Add a badge for the new workflow to the README.md security/CI section.

Document the .claw.json / .claude.json configuration schema in a dedicated docs/CONFIG.md file

The repo exposes .claw.json at the root and rust/.claw.json as configuration entry points, and .claude.json / CLAUDE.md appear to configure the AI-assisted coding workflow, yet USAGE.md, docs/MODEL_COMPATIBILITY.md, and docs/container.md contain no reference to the schema or accepted keys for these files. New contributors trying to configure their own Claw Code instance have no authoritative reference, and check_doc_source_of_truth.py in .github/scripts/ implies there is already tooling to enforce doc coverage — meaning this gap will likely be caught by CI eventually anyway.

• [ ] Inspect the actual contents of `.claw

Good first issues

1. Add integration tests under rust/crates/ for the claw doctor subcommand — the CI workflow exists but test coverage for health-check logic is not evidenced in the file list. 2. Expand docs/MODEL_COMPATIBILITY.md with a concrete compatibility matrix — the file exists but given the repo's purpose (AI agent harness), documenting which Claude/model versions are supported is a clear gap. 3. Write a CONTRIBUTING.md — the repo has USAGE.md, PHILOSOPHY.md, ROADMAP.md, and PARITY.md but no contributor guide describing how to add a new crate under rust/crates/ or how to run the Python doc audit script locally.

Top contributors

• @Yeachan-Heo — 73 commits
• @code-yeongyu — 26 commits
• @sigridjineth — 1 commits

Recent commits

• caeac82 — fix(permissions): return guidance for multi-word forms instead of falling through to LLM (#2994) (code-yeongyu)
• 85435ad — fix(plugins): route plugin and marketplace aliases through local handler (#2993) (code-yeongyu)
• 5eb4b8a — fix(mcp): return typed error JSON for unsupported actions (info/describe/list-filter) (#2989) (code-yeongyu)
• 65aa559 — fix: support /plugins slash command in resume mode (#2973) (code-yeongyu)
• ac8a24b — fix(config): emit section and section_value in JSON output for config subcommands (#2990) (code-yeongyu)
• 94b80a0 — fix(skills): route show/info/list-filter to local, not model invoke (#2988) (code-yeongyu)
• 9b97c4d — fix(tests): isolate CLAW_CONFIG_HOME in resumed_status JSON test (#2992) (code-yeongyu)
• 1206f41 — fix(resume): emit structured JSON for /agents --output-format json (#2987) (code-yeongyu)
• c993303 — fix(version): add build_date and executable_path to version JSON output (code-yeongyu)
• 8e45f18 — test(output_format_contract): add plugins json coverage to inventory_commands test (#2972) (code-yeongyu)

Security observations

• High · Sensitive Session Data Committed to Version Control — .claude/sessions/, rust/.claude/sessions/, rust/.claw/sessions/. Numerous Claude AI session files (.claude/sessions/*.json, rust/.claude/sessions/*.json, rust/.claw/sessions/*.jsonl) are committed to the repository. These session files may contain sensitive information including API keys, authentication tokens, conversation history, command outputs, file contents, and other secrets exchanged during development sessions. Fix: Immediately audit all session files for sensitive data. Add session directories to .gitignore (e.g., .claude/, .claw/, .omc/). Rotate any credentials or API keys that may have been exposed. Use git-filter-repo or BFG Repo Cleaner to purge these files from git history.
• High · Development Artifact and Internal State Files in Version Control — rust/.omc/, rust/.clawd-todos.json, rust/.sandbox-home/, .claw.json, rust/.claw.json, .claude.json, prd.json, progress.txt. Internal planning files (rust/.omc/plans/tui-enhancement-plan.md), todo files (rust/.clawd-todos.json), sandbox home directory (rust/.sandbox-home/), and configuration files (.claw.json, rust/.claw.json, .claude.json, prd.json, progress.txt) are committed to the repository. These may expose internal architecture details, development workflows, infrastructure information, or sensitive configuration state. Fix: Add all tooling artifact directories and internal state files to .gitignore. Review each file for sensitive content before any future commits. Purge sensitive files from git history using BFG Repo Cleaner or git-filter-repo.
• High · Sandbox Home Directory Committed to Repository — rust/.sandbox-home/. The directory rust/.sandbox-home/ (including rust/.sandbox-home/.rustup/settings.toml) represents a sandbox user home directory committed to version control. Home directories can contain shell history, SSH keys, credential files, tool configuration with embedded tokens, and other highly sensitive data. Fix: Immediately remove rust/.sandbox-home/ from the repository. Audit its contents for any sensitive credentials or keys. Add to .gitignore. Purge from git history.
• Medium · Missing Security Policy and Vulnerability Disclosure Process — Repository root. The repository lacks a SECURITY.md file defining a vulnerability disclosure policy, security contact, or responsible disclosure process. Given the repository's high visibility (claimed 100K+ stars), the absence of a security policy increases risk from uncoordinated vulnerability disclosure. Fix: Create a SECURITY.md file documenting the security policy, how to report vulnerabilities privately (e.g., GitHub private security advisories), and the expected response timeline.
• Medium · install.sh Script Without Integrity Verification — install.sh. The presence of install.sh as a shell installer script is a common pattern that, if distributed via curl-pipe-bash (e.g., curl ... | sh), poses significant risk. There is no evidence of checksum verification, code signing, or integrity checks in the file structure. This pattern is susceptible to MITM attacks and supply chain compromise. Fix: Ensure install.sh is served over HTTPS only. Add SHA256 checksum verification for downloaded binaries. Consider using cryptographic signatures (e.g., cosign, minisign). Document the verification process in README. Avoid curl-pipe-bash patterns if possible; prefer package manager distributions.
• Medium · FUNDING.yml May Indicate Supply Chain / Trust Concerns — .github/FUNDING.yml. The .github/FUNDING.yml file combined with a very rapid star acquisition trajectory (claimed fastest to 100K stars) are indicators sometimes associated with artificially inflated repositories used for social engineering or malicious distribution. This warrants scrutiny of the supply chain integrity of the distributed binaries. Fix: Ensure release binaries are built exclusively via the CI/CD pipeline (.github/workflows/release.yml) with reproducible builds and signed artifacts. Enable GitHub branch protection and require code review for all changes to release workflows.
• Medium · Release Workflow May Lack Supply Chain Security Controls — undefined. The .github/workflows/release.yml CI/CD pipeline is present but cannot be fully audited from the provided information. Release pipelines without Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.