If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ultraworkers/claw-code-parity shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 5w ago
• 2 active contributors
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 52% of recent commits
• ⚠ No license — legally unclear to depend on

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

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ultraworkers/claw-code-parity repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ultraworkers/claw-code-parity.

What it runs against: a local clone of ultraworkers/claw-code-parity — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ultraworkers/claw-code-parity | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 63 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ultraworkers/claw-code-parity. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ultraworkers/claw-code-parity.git
#   cd claw-code-parity
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ultraworkers/claw-code-parity and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ultraworkers/claw-code-parity(\\.git)?\\b" \\
  && ok "origin remote is ultraworkers/claw-code-parity" \\
  || miss "origin remote is not ultraworkers/claw-code-parity (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "rust/Cargo.toml" \\
  && ok "rust/Cargo.toml" \\
  || miss "missing critical file: rust/Cargo.toml"
test -f "rust/crates/api/src/lib.rs" \\
  && ok "rust/crates/api/src/lib.rs" \\
  || miss "missing critical file: rust/crates/api/src/lib.rs"
test -f "rust/crates/api/src/client.rs" \\
  && ok "rust/crates/api/src/client.rs" \\
  || miss "missing critical file: rust/crates/api/src/client.rs"
test -f "rust/crates/api/src/providers/mod.rs" \\
  && ok "rust/crates/api/src/providers/mod.rs" \\
  || miss "missing critical file: rust/crates/api/src/providers/mod.rs"
test -f "rust/crates/api/src/sse.rs" \\
  && ok "rust/crates/api/src/sse.rs" \\
  || miss "missing critical file: rust/crates/api/src/sse.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 63 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~33d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ultraworkers/claw-code-parity"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A Rust port of the claw-code project that implements autonomous AI agent workflows for code generation and repository maintenance. It bridges Python-based agent orchestration with high-performance Rust execution, enabling self-maintaining codebases through parallel coding sessions, event-driven task scheduling, and machine-readable state tracking — currently in active parity work between the original and Rust implementations. Monorepo rooted at rust/ with Cargo workspace (Cargo.toml at root with members = ["crates/*"]). The structure uses .claude/sessions/ for AI agent session state tracking (23+ session files suggesting parallel agent workflows), and reference documentation in root markdown files (USAGE.md, PHILOSOPHY.md, PARITY.md). Core Rust crates live under rust/crates/* but specific crate names not visible in file list — inspect rust/Cargo.toml for details.

AI/ML engineers and DevOps practitioners building autonomous code generation systems who need a performant, type-safe backend for agent orchestration; contributors to the ultraworkers/claw-code ecosystem who are migrating from Python to Rust for production workloads.

Highly notable but actively transitional: the project achieved 50K GitHub stars in 2 hours (unprecedented), indicating strong community signal, but this repo is explicitly temporary while claw-code undergoes migration. The Rust workspace is actively developed (many session files from Jan 2025), CI/CD is set up (rust-ci.yml), but it's pre-1.0 (v0.1.0) and not yet published. Verdict: actively developed but experimental — parity work in progress, not yet production-ready.

This is a migration-in-flight project with inherent bifurcation risk: the Python original and Rust port must maintain behavioral parity, increasing the surface area for subtle bugs. Single-author risk is moderate (Bellman/Yeachan Heo + friends visible in README, but autonomous agents are the stated maintainers). The workspace has minimal published dependencies visible (only serde_json listed), but the full dependency tree and external integrations (clawhip, oh-my-openagent, oh-my-codex) are in companion repos, creating distributed maintenance complexity. No indication of open issues visible in the file list.

Active parity validation work: the repo contains explicit PARITY.md documentation and 33+ recent .claude session files (dated Jan 2025) indicating ongoing agent-driven development and testing. The rust/ workspace has continuous integration configured (rust-ci.yml workflow), and the project is simultaneously maintaining this repo while the original claw-code undergoes Rust migration. Focus appears to be on ensuring behavioral equivalence between implementations.

Clone and build the Rust workspace:

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

For context on the project structure and local testing workflows, read USAGE.md and PARITY.md in the root directory first.

Daily commands: Per USAGE.md (referenced as mandatory reading in the README), exact run commands depend on the use case (build, auth, CLI invocation, session management, parity harness). Root-level command: cargo build -p <crate-name> after identifying crate names under rust/crates/. For testing: cargo test --workspace. Inspect USAGE.md and rust/README.md for CLI-specific invocations.

• rust/Cargo.toml — Workspace root configuration defining all member crates, shared dependencies, and linting rules — essential for understanding the monorepo structure and build constraints.
• rust/crates/api/src/lib.rs — API crate entry point exposing the client interface and provider abstractions — every API interaction flows through this module.
• rust/crates/api/src/client.rs — Core client implementation handling request/response logic and provider dispatch — the load-bearing integration layer.
• rust/crates/api/src/providers/mod.rs — Provider abstraction and routing system for Anthropic and OpenAI-compatible services — critical for multi-provider support.
• rust/crates/api/src/sse.rs — Server-Sent Events streaming implementation for real-time response handling — essential for understanding async communication patterns.
• rust/crates/mock-anthropic-service/src/main.rs — Mock Anthropic service entry point used for testing and parity validation — demonstrates the expected API contract.
• PARITY.md — Project parity specification document defining what features must match the original implementation — guiding principle for this port.

Add a new LLM provider

1. Create a new provider module file (e.g., providers/claude_native.rs) implementing the Provider trait (rust/crates/api/src/providers/claude_native.rs)
2. Export the new provider in the providers module and register it in the router match statement (rust/crates/api/src/providers/mod.rs)
3. Add provider-specific request/response types to the shared types module if needed (rust/crates/api/src/types.rs)
4. Write integration tests for the new provider in the tests directory (rust/crates/api/tests/provider_client_integration.rs)
5. Update PARITY.md to document the new provider support (PARITY.md)

Add a new command-line command

1. Define the command structure and handler in the commands crate library (rust/crates/commands/src/lib.rs)
2. Register the command in the main command router/dispatcher (rust/crates/commands/src/lib.rs)
3. Integrate with the API client to invoke appropriate provider operations (rust/crates/api/src/client.rs)
4. Add command documentation to the USAGE guide (rust/USAGE.md)

Add a new plugin or hook

1. Create a new bundled plugin directory with .claude-plugin metadata (rust/crates/plugins/bundled/example-bundled/.claude-plugin/plugin.json)
2. Implement hook scripts (pre.sh, post.sh) in the hooks directory (rust/crates/plugins/bundled/example-bundled/hooks/post.sh)
3. Register the plugin in the plugins crate configuration (rust/crates/plugins/Cargo.toml)
4. Test plugin execution through the compat-harness validation (rust/crates/compat-harness/src/lib.rs)

Optimize request handling with prompt caching

1. Configure cache policies and TTL in the prompt cache module (rust/crates/api/src/prompt_cache.rs)
2. Update the client to check cache before making provider requests (rust/crates/api/src/client.rs)
3. Add cache validation tests to ensure correctness (rust/crates/api/tests/client_integration.rs)

• Rust — Provides memory safety, zero-cost abstractions, and high concurrency performance essential for a production CLI tool and API client; enables the forbid(unsafe_code) constraint for reliability.
• Cargo workspaces with multiple crates — Enforces clean separation of concerns (api, commands, plugins, testing) while maintaining shared dependency management and allowing independent compilation and testing of subsystems.
• Server-Sent Events (SSE) streaming — Enables real-time streaming responses from LLM providers, reducing latency for long-running requests and improving user experience with progressive output.
• Provider abstraction pattern — Decouples client logic from provider-specific implementations, allowing seamless support for Anthropic, OpenAI-compatible, and future providers without duplicating core functionality.
• Prompt caching — Reduces API costs and latency by caching repeated prompts and their responses, critical for interactive CLI tools and repetitive batch operations.

• Temporary Rust port of original codebase (not greenfield)

  • Why: Required to validate parity with the original implementation while the main claw-code repository undergoes migration; ensures no functionality is lost during the transition.
  • Consequence: Code must closely mirror original behavior, limiting refactoring and optimization opportunities; tight parity constraints reduce iteration speed but ensure user expectations are met.

• Forbid unsafe code in workspace lints

  • Why: Maximizes memory safety and eliminates undefined behavior risks at the cost of preventing FFI and performance micro-optimizations that might require unsafe blocks.
  • Consequence: Cannot use low-level unsafe optimizations; must solve all problems with safe abstractions, which may result in slightly higher runtime overhead in CPU-bound operations.

• Monolithic API client instead of auto-generated SDK

  • Why: Allows precise control over request/response handling, streaming integration, and caching logic tailored to the CLI use case rather than generic SDK generation.
  • Consequence: Manual maintenance burden for API contract changes; requires explicit testing against provider API changes; more control but higher dev cost than auto-generated clients.

• Real-time collaboration or multi-user session management — designed for single-user CLI workflows
• Persistent state management or database layer — focuses on stateless request/response processing
• Authentication beyond API key credential handling — assumes provider authentication is external
• Cross-platform GUI — this is a CLI-first tool without graphical interface aspirations
• WebSocket support — uses HTTP/SSE streaming instead of bidirectional WebSocket channels
• Offline operation — requires live connection to LLM providers

1. Parity is non-negotiable: this repo is not a fresh Rust implementation but a migration validator; your changes must not diverge from the original claw-code behavior. Always check PARITY.md before committing. 2. Agent session files are state, not tests: the .claude/sessions/ directory contains serialized agent orchestration history; do not manually edit or commit changes to these files casually—they are managed by clawhip/oh-my-openagent. 3. Monorepo discovery: specific crate names and their purposes are not visible in the file list provided; you must read rust/Cargo.toml and rust/README.md immediately to understand module layout. 4. Ecosystem dependencies: this project relies on companion repos (clawhip, oh-my-openagent, oh-my-claudecode, oh-my-codex) for orchestration; local development may require those to be cloned/linked separately—check USAGE.md for integration instructions. 5. Version pinning: workspace.package is set to v0.1.0 across all crates; any breaking change in a crate requires coordinated version bumps.

• Parity Testing & Migration Validation — This repo's entire purpose is to ensure a Rust port behaves identically to a Python original; understanding parity testing patterns (cross-language behavior equivalence, oracle comparison, differential testing) is central to contributing.
• Autonomous Agent Orchestration — The codebase is maintained by AI agents coordinating through clawhip; grasping how sessions, state machines, and event-driven task scheduling work explains why .claude/sessions/ exists and how features land.
• Monorepo Workspace Management (Cargo) — rust/crates/* is a multi-crate workspace with shared dependencies and version pinning; Cargo workspaces are non-trivial—misunderstanding resolver, member paths, or dependency inheritance can break builds.
• Linting as a First-Class Constraint — The workspace forbids unsafe code, enforces Clippy pedantic rules, and has opinionated allow-lists (module_name_repetitions, missing_panics_doc); PRs fail on lint violations, making code style non-negotiable.
• Machine-Readable State & Session Serialization — Sessions are stored as JSON (.claude/sessions/*.json) for agent introspection and replay; understanding how session state is serialized and deserialized is critical for debugging agent workflows and avoiding merge conflicts.
• Event-Driven Orchestration & Recovery Loops — The PHILOSOPHY mentions 'recovery loops' and 'event-driven orchestration'—these are patterns where agent failures trigger retry/remediation workflows; understanding the event model and recovery semantics helps you write agent-friendly code.
• Multi-Language Interop & FFI Considerations — This repo bridges Rust and Python (via clawhip, oh-my-openagent, oh-my-claudecode); even if you're only writing Rust, you need to understand serialization boundaries, error propagation across languages, and how JSON becomes the interchange format.

• ultraworkers/claw-code — The original Python implementation that this repo maintains parity with; go here for the reference behavior and longer-term roadmap.
• Yeachan-Heo/clawhip — The orchestration engine for autonomous agent workflows; this repo depends on clawhip for parallel coding sessions and state machine coordination.
• code-yeongyu/oh-my-openagent — Agent framework used to build autonomous claw workers; understanding this is essential for hacking on the agent loop integration in claw-code-parity.
• Yeachan-Heo/oh-my-claudecode — Claude API integration layer for code generation; consumed by claw-code-parity to invoke LLM-based code tasks.
• Yeachan-Heo/oh-my-codex — Code indexing and search layer for the claw ecosystem; likely used for codebase introspection and dependency analysis in parity validation.

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 Rust integration tests for parity verification harness

The repo has MOCK_PARITY_HARNESS.md and PARITY.md documenting parity requirements between the original claw-code and Rust port, but there are no visible integration tests in rust/tests/ directory. New contributors could create a comprehensive test suite that validates parity against the documented specification, ensuring the Rust implementation matches the original behavior.

• [ ] Create rust/tests/parity_integration_tests.rs with test cases derived from MOCK_PARITY_HARNESS.md
• [ ] Reference specific parity requirements from rust/PARITY.md and add assertions for each
• [ ] Add a test helper module in rust/tests/common/mod.rs for shared test fixtures
• [ ] Integrate tests into rust-ci.yml GitHub Action workflow to run on each commit

Implement missing crates structure for modular Rust port

The Cargo.toml shows a workspace with 'members = ["crates/*"]' but the file structure doesn't show any subdirectories under rust/crates/. This is a critical gap for organizing the Rust rewrite. Contributors should create the modular crate structure that mirrors the original claw-code architecture.

• [ ] Analyze PHILOSOPHY.md and ROADMAP.md to identify logical module boundaries
• [ ] Create rust/crates/core/Cargo.toml, rust/crates/cli/Cargo.toml, and rust/crates/tui/Cargo.toml (based on TUI-ENHANCEMENT-PLAN.md)
• [ ] Move existing code into appropriate crates/ subdirectories with proper lib.rs/main.rs
• [ ] Update rust/Cargo.lock and verify workspace builds with 'cargo build --workspace'

Add structured error handling and custom error types across crates

The workspace lints forbid unsafe_code but there's no visible custom error type definition in the file structure. Given the missing_errors_doc lint is suppressed, contributors should implement proper error handling patterns using a dedicated errors crate or module, reducing the need for panic suppression.

• [ ] Create rust/crates/errors/src/lib.rs with custom Error and Result types using thiserror or anyhow
• [ ] Add error variants for common failure modes documented in PARITY.md (e.g., CompilationError, ValidationError)
• [ ] Add #[error] doc comments to each error variant (enabling missing_errors_doc lint)
• [ ] Update existing crate dependencies to use the new error types and document error conditions in function docs

• Add #[must_use] attributes and docstrings to public functions under rust/crates/*/src/lib.rs that currently lack them—improves API ergonomics and catches silent errors. Search for pub fn that don't have these attributes.
• Expand the parity-harness testing: review PARITY.md to identify high-risk behaviors (agent session state transitions, error recovery paths) not yet covered by integration tests, then add concrete test cases under rust/crates/*/tests/. Look for gaps between the spec and test code.
• Document each crate's purpose and public API in rust/crates/*/README.md or rust/README.md under a new 'Crate Reference' section—currently only high-level structure is described, making it hard for new contributors to know where their code belongs.

The codebase demonstrates generally good security practices with unsafe_code forbidden and comprehensive lint configurations enabled. However, there is a critical configuration issue: session files containing potentially sensitive information are being tracked in version control. This requires immediate remediation. The project would benefit from adding a SECURITY.md file, implementing automated dependency auditing in CI/CD (evidenced by rust-ci.yml workflow), and tightening version constraints on dependencies. No hardcoded secrets, injection vulnerabilities, or obvious misconfigurations were detected in the provided file structure and configuration snippets.

• Medium · Excessive Session Files in Source Control — .claude/sessions/, rust/.claude/sessions/. The repository contains numerous .claude/sessions/ directories with session JSON files (40+ files across root and rust/ directories). These session files may contain sensitive information such as API keys, authentication tokens, or conversation history with confidential data. Session files should not be stored in version control. Fix: Add .claude/sessions/ to .gitignore immediately. Review git history to determine if sensitive data was exposed and rotate any potentially compromised credentials. Consider using environment variables for sensitive session data.
• Low · Missing Security Policy — Repository root. No SECURITY.md file found in the repository root. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with clear instructions for reporting security vulnerabilities, including a responsible disclosure process and security contact information.
• Low · Permissive Clippy Lints Configuration — Cargo.toml - [workspace.lints.clippy]. While the project forbids unsafe_code and enables pedantic lints, some important security-related clippy checks (like potential panics and error handling) are suppressed with 'allow' directives. Fix: Review and reduce the scope of allowed lints. Consider keeping missing_panics_doc and missing_errors_doc at 'warn' level for security-critical code, or maintain separate lint profiles for different crates.
• Low · Unclear Dependency Management — Cargo.toml - [workspace.dependencies]. The workspace uses serde_json without specifying patch version constraints (version = '1' allows any 1.x.x version). While this enables compatibility, it may introduce unexpected behavior changes in minor updates. Fix: Consider using more specific version constraints like '1.0' or '1.0.x' for critical dependencies. Implement dependency auditing in CI/CD using 'cargo audit' to detect known vulnerabilities.

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

• 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.