claw-code Documentation

An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.

195,006 stars Rust Rust 1 file · ~5,514 tokens
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy claw-code on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name claw-code -p 6333:6333 --restart always qdrant/qdrant:latest
Configured Services & Ports
⚙️ qdrant
image: qdrant/qdrant:latest
🔌 Ports: 6333:6333, 6334:6334
⚙️ rag-serve
image: build locally
🔌 Ports: 8787:8787
⚙️ rag-ingest
image: build locally
docker-compose.yml
yaml (docker-compose.yml) 
services:
  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
      - "6334:6334"
    environment:
      QDRANT__SERVICE__GRPC_PORT: "6334"
    volumes:
      - qdrant-storage:/qdrant/storage

  rag-serve:
    build:
      context: ./rust
      dockerfile: crates/claw-rag-service/Dockerfile
    command: ["serve", "--db", "/data/index.sqlite"]
    environment:
      # Use mock embeddings by default for local dev; override in your shell for real providers.
      CLAW_RAG_MOCK_PROVIDERS: "1"
      CLAW_RAG_DB: "/data/index.sqlite"
      CLAW_RAG_HOST: "0.0.0.0"
      CLAW_RAG_QDRANT_URL: "http://qdrant:6334"
      CLAW_RAG_QDRANT_COLLECTION: "claw_rag_chunks"
    ports:
      - "8787:8787"
    depends_on:
      - qdrant
    volumes:
      - rag-data:/data

  rag-ingest:
    build:
      context: ./rust
      dockerfile: crates/claw-rag-service/Dockerfile
    command: ["ingest", "--db", "/data/index.sqlite"]
    environment:
      CLAW_RAG_MOCK_PROVIDERS: "1"
      CLAW_RAG_DB: "/data/index.sqlite"
      CLAW_RAG_QDRANT_URL: "http://qdrant:6334"
      CLAW_RAG_QDRANT_COLLECTION: "claw_rag_chunks"
    depends_on:
      - qdrant
    volumes:
      - rag-data:/data
      # Mount example workspace roots under /workspaces
      - ./:/workspaces/main:ro

volumes:
  qdrant-storage:
  rag-data:

File: README.md

Claw Code

start with the real crab-powered harnesses

[!IMPORTANT]
Claw Code is not the serious production project here.
This repository is closer to a museum exhibit than a product pitch, a crustacean-run artifact kept alive by clawed gajaes, swept and labeled by agents, and automatically maintained according to the harnesses above.

As already described in the project philosophy, this is not meant to be hand-operated like a normal product repo. It is an agent-managed exhibit: the harnesses plan, execute, verify, label, and preserve the artifact while the crabs keep the tank running.

If you want to actually run work, start with LazyCodex or Gajae-Code. If you want to inspect the strange little fossil of the Claw Code moment, continue below.

For the longer public explanation behind this philosophy, see here.

Claw Code is the public Rust implementation of the claw CLI agent harness.
The canonical implementation lives in rust/, and the current source of truth for this repository is ultraworkers/claw-code.

[!IMPORTANT]
Start with USAGE.md for build, auth, CLI, session, and parity-harness workflows. For file submission/navigation questions, see Navigation and file context. For local OpenAI-compatible models and offline skill installs, see Local OpenAI-compatible providers and skills setup. Windows users can jump to the PowerShell-first Windows install and release quickstart. Make claw doctor your first health check after building, use rust/README.md for crate-level details, read PARITY.md for the current Rust-port checkpoint, and see docs/container.md for the container-first workflow.

ACP / Zed status: claw-code does not ship an ACP/Zed daemon or JSON-RPC 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, returns status with exit code 0, and real ACP support remains tracked separately in ROADMAP.md. For the public JSON contract, see docs/g011-acp-json-rpc-status-contract.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"

# 5. Start an interactive session
./target/debug/claw

[!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 https://rustup.rs/ 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"

For release ZIPs, PATH setup, provider switching, and notification smoke checks, see docs/windows-install-release.md.

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

PowerShell smoke commands that do not require live credentials:

powershell
$env:CLAW_CONFIG_HOME = Join-Path $env:TEMP "claw config home"
New-Item -ItemType Directory -Force -Path $env:CLAW_CONFIG_HOME | Out-Null
Remove-Item Env:\ANTHROPIC_API_KEY, Env:\ANTHROPIC_AUTH_TOKEN, Env:\OPENAI_API_KEY -ErrorAction SilentlyContinue
.\rust\target\debug\claw.exe help
.\rust\target\debug\claw.exe status
.\rust\target\debug\claw.exe config env
.\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

Ecosystem

Claw Code is built in the open alongside the broader UltraWorkers toolchain:

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.

File: rust/README.md

🦞 Claw Code — Rust Implementation

A high-performance Rust rewrite of the Claw Code CLI agent harness. Built for speed, safety, and native tool execution.

For a task-oriented guide with copy/paste examples, see ../USAGE.md.

Quick Start

bash
# Inspect available commands
cd rust/
cargo run -p rusty-claude-cli -- --help

# Build the workspace
cargo build --workspace

# Run the interactive REPL
cargo run -p rusty-claude-cli -- --model claude-opus-4-7

# One-shot prompt
cargo run -p rusty-claude-cli -- prompt "explain this codebase"

# JSON output for automation
cargo run -p rusty-claude-cli -- --output-format json prompt "summarize src/main.rs"

Configuration

Set your API credentials:

bash
export ANTHROPIC_API_KEY="sk-ant-..."
# Or use a proxy
export ANTHROPIC_BASE_URL="https://your-proxy.com"

Or provide an OAuth bearer token directly:

bash
export ANTHROPIC_AUTH_TOKEN="anthropic-oauth-or-proxy-bearer-token"

For local OpenAI-compatible servers such as Ollama, including Qwen reasoning
models, see ../docs/local-openai-compatible-providers.md.
Use the exact model tag exposed by the server, for example qwen3:latest, and
prefer OLLAMA_HOST for Ollama-specific local routing.

Mock parity harness

The workspace now includes a deterministic Anthropic-compatible mock service and a clean-environment CLI harness for end-to-end parity checks.

bash
cd rust/

# Run the scripted clean-environment harness
./scripts/run_mock_parity_harness.sh

# Or start the mock service manually for ad hoc CLI runs
cargo run -p mock-anthropic-service -- --bind 127.0.0.1:0

Harness coverage:

  • streaming_text
  • read_file_roundtrip
  • grep_chunk_assembly
  • write_file_allowed
  • write_file_denied
  • multi_tool_turn_roundtrip
  • bash_stdout_roundtrip
  • bash_permission_prompt_approved
  • bash_permission_prompt_denied
  • plugin_tool_roundtrip

Primary artifacts:

  • crates/mock-anthropic-service/ — reusable mock Anthropic-compatible service
  • crates/rusty-claude-cli/tests/mock_parity_harness.rs — clean-env CLI harness
  • scripts/run_mock_parity_harness.sh — reproducible wrapper
  • scripts/run_mock_parity_diff.py — scenario checklist + PARITY mapping runner
  • mock_parity_scenarios.json — scenario-to-PARITY manifest

Features

Feature Status
Anthropic / OpenAI-compatible provider flows + streaming ✅
Direct bearer-token auth via ANTHROPIC_AUTH_TOKEN ✅
Interactive REPL (rustyline) ✅
Tool system (bash, read, write, edit, grep, glob) ✅
Web tools (search, fetch) ✅
Sub-agent / agent surfaces ✅
Todo tracking ✅
Notebook editing ✅
CLAUDE.md / CLAW.md / AGENTS.md project memory ✅
Config file hierarchy (.claw.json + merged config sections) ✅
Permission system ✅
MCP server lifecycle + inspection ✅
Session persistence + resume ✅
Cost / usage / stats surfaces ✅
Git integration ✅
Markdown terminal rendering (ANSI) ✅
Model aliases (opus/sonnet/haiku) ✅
Direct CLI subcommands (status, sandbox, agents, mcp, skills, doctor) ✅
Slash commands (including /skills, /agents, /mcp, /doctor, /plugin, /subagent) ✅
Hooks (/hooks, config-backed lifecycle hooks) ✅
Plugin management surfaces ✅
Skills inventory / install / uninstall surfaces ✅
Machine-readable JSON output across core CLI surfaces ✅

Model Aliases

Short names resolve to the latest model versions:

Alias Resolves To
opus claude-opus-4-7
sonnet claude-sonnet-4-6
haiku claude-haiku-4-5-20251213

CLI Flags and Commands

Representative current surface:

text
claw [OPTIONS] [COMMAND]

Flags:
  --model MODEL
  --output-format text|json  (case-insensitive; CLAW_OUTPUT_FORMAT supplies the default, flags override env)
  --permission-mode MODE
  --cwd PATH, -C PATH, --directory PATH
  --dangerously-skip-permissions, --skip-permissions
  --allowedTools TOOLS        canonical snake_case names or aliases; status JSON exposes allowed_tools.available/aliases
  --resume [SESSION.jsonl|session-id|latest]
  --version, -V

Top-level commands:
  prompt <text>
  help
  version
  status
  sandbox
  acp [serve]
  dump-manifests
  bootstrap-plan
  agents
  mcp
  skills
  system-prompt
  init

claw acp is a local discoverability surface for editor-first users: it reports the current ACP/Zed status without starting the runtime. As of April 16, 2026, claw-code does not ship an ACP/Zed daemon or JSON-RPC entrypoint yet, and claw acp serve is only a status alias until the real protocol surface lands. Status queries exit 0 and expose the same machine-readable contract via --output-format json; malformed ACP invocations exit 1 with kind: unsupported_acp_invocation.
--output-format accepts text or json in any casing. CLAW_OUTPUT_FORMAT=json selects JSON as the default for non-interactive commands, explicit flags override it, repeated flags warn on stderr, and status JSON exposes format_source, format_raw, and format_overridden. Help and doctor output also surface CLAW_LOG / RUST_LOG as the logging environment knobs.
claw version --output-format json is the provenance probe for automation: it reports full git_sha, derived git_sha_short, is_dirty, branch, commit_date, commit_timestamp, rustc_version, runtime executable_path, and binary_provenance; the text report is available as human_readable instead of a duplicate message field.
status --output-format json reports loaded project memory files under workspace.memory_files[] with each file's path, source (claude_md, claw_md, agents_md, or scoped/rule sources), origin, scope_path, outside_project, chars, and contributes; claw doctor --output-format json includes a dedicated memory check. Root instruction-file priority is CLAUDE.md, then CLAW.md, then AGENTS.md, discovery is bounded to the current git root when present (otherwise cwd only), and all non-duplicate loaded files contribute to the rendered system prompt.
claw mcp --output-format json reports partial MCP config success: valid servers remain in servers[] while malformed siblings appear in invalid_servers[], with total_configured, valid_count, and invalid_count split out for automation. status mirrors this as mcp_validation, and doctor includes an mcp validation check.
status --output-format json also reports partial hook config success under hook_validation: valid hook entries are retained while malformed or unknown-event siblings appear in invalid_hooks[], with valid_count, invalid_count, and typed kind fields (invalid_hooks_config or unknown_hook_event) for automation. doctor --output-format json includes a hook validation check, and config --output-format json includes hook_validation metadata with degraded status when invalid entries exist.
Shorthand prompt mode honors the POSIX -- end-of-flags separator, so claw -- "-prompt-with-dash" and unknown dash-prefixed non-flag text stay on the prompt path instead of being treated as CLI options.
claw dump-manifests is self-contained: it emits the Rust resolver inventory for the selected workspace (commands, tools, agents, skills, and bootstrap phases) without requiring an upstream Claude Code TypeScript checkout. Use --manifests-dir PATH only to scope resolver discovery to another directory.

The command surface is moving quickly. For the canonical live help text, run:

bash
cargo run -p rusty-claude-cli -- --help

Slash Commands (REPL)

Tab completion expands slash commands, model aliases, permission modes, and recent session IDs.

The REPL now exposes a much broader surface than the original minimal shell:

  • session / visibility: /help, /status, /sandbox, /cost, /resume, /session, /version, /usage, /stats
  • workspace / git: /compact, /clear, /config, /memory, /init, /diff, /commit, /pr, /issue, /export, /hooks, /files, /release-notes
  • discovery / debugging: /mcp, /agents, /skills, /doctor, /tasks, /context, /desktop
  • automation / analysis: /review, /advisor, /insights, /security-review, /subagent, /team, /telemetry, /providers, /cron, and more
  • plugin management: /plugin (with aliases /plugins, /marketplace)

Notable claw-first surfaces now available directly in slash form:

  • /skills [list|show <name>|install |uninstall <name>|help]
  • /agents [list|show <name>|create <name>|help]
  • /mcp [list|show <server>|help]
  • /doctor
  • /plugin [list|install |enable <name>|disable <name>|uninstall |update ]
  • /subagent [list|steer <target> <msg>|kill ]

See ../USAGE.md for usage examples and run cargo run -p rusty-claude-cli -- --help for the live canonical command list.

Workspace Layout

text
rust/
├── Cargo.toml              # Workspace root
├── Cargo.lock
└── crates/
    ├── api/                # Provider clients + streaming + request preflight
    ├── commands/           # Shared slash-command registry + help rendering
    ├── compat-harness/     # Compatibility/parity harness utilities
    ├── mock-anthropic-service/ # Deterministic local Anthropic-compatible mock
    ├── plugins/            # Plugin metadata, manager, install/enable/disable surfaces
    ├── runtime/            # Session, config, permissions, MCP, prompts, auth/runtime loop
    ├── rusty-claude-cli/   # Main CLI binary (`claw`)
    ├── telemetry/          # Session tracing and usage telemetry types
    └── tools/              # Built-in tools, skill resolution, tool search, agent runtime surfaces

Crate Responsibilities

  • api — provider clients, SSE streaming, request/response types, auth (ANTHROPIC_API_KEY + bearer-token support), request-size/context-window preflight
  • commands — slash command definitions, parsing, help text generation, JSON/text command rendering
  • compat-harness — compatibility and parity helpers for comparing behavior with upstream fixtures
  • mock-anthropic-service — deterministic /v1/messages mock for CLI parity tests and local harness runs
  • plugins — plugin metadata, install/enable/disable/update flows, plugin tool definitions, hook integration surfaces
  • runtime — ConversationRuntime, config loading, session persistence, permission policy, MCP client lifecycle, system prompt assembly, usage tracking
  • rusty-claude-cli — REPL, one-shot prompt, direct CLI subcommands, streaming display, tool call rendering, CLI argument parsing
  • telemetry — session trace events and supporting telemetry payloads
  • tools — tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, and runtime-facing tool discovery

Stats

  • ~20K lines of Rust
  • 9 crates in workspace
  • Binary name: claw
  • Default model: claude-opus-4-7
  • Default permissions: workspace-write

License

See repository root.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →