claw-code

Claw Code

English · 中文

start with the real crab-powered harnesses

github.com/code-yeongyu/lazycodex
github.com/Yeachan-Heo/gajae-code

Join the Discords: ultraworkers discord · gajae-code discord

[!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.

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

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:

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.

# 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:

   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):

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

4. Run (PowerShell — note .exe and backslash):

   $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:

# 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:

$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)

ln -s $(pwd)/rust/target/debug/claw /usr/local/bin/claw

Then reload your shell and test:

claw --help

Option 2: Use cargo install (all platforms)

Build and install to Cargo's default location (~/.cargo/bin/, which is usually on PATH):

# 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:

export PATH="$(pwd)/rust/target/debug:$PATH"

Reload your shell:

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:

cd rust
cargo test --workspace

Documentation map

• USAGE.md — quick commands, auth, sessions, config, parity harness
• docs/navigation-file-context.md — terminal navigation, scrollback, @path file context, attachments, and secret-safety guidance
• docs/local-openai-compatible-providers.md — Ollama/llama.cpp/vLLM setup, Claw multi-provider positioning, and local skills install checks
• docs/windows-install-release.md — PowerShell-first install, release artifact, provider switching, and Windows/WSL notification smoke paths
• rust/README.md — crate map, CLI surface, features, workspace layout
• PARITY.md — parity status for the Rust port
• rust/MOCK_PARITY_HARNESS.md — deterministic mock-service harness details
• ROADMAP.md — active roadmap and open cleanup work
• docs/g004-events-reports-contract.md — Stream 2 lane event/report contract guidance for consumers
• PHILOSOPHY.md — why the project exists and how it is operated
• CONTRIBUTING.md, SECURITY.md, SUPPORT.md, and CODE_OF_CONDUCT.md — contribution, vulnerability-reporting, support, and community policies
• LICENSE — MIT license for this repository

Ecosystem

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

• clawhip
• oh-my-openagent
• oh-my-claudecode
• oh-my-codex
• gajae-code
• UltraWorkers Discord

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

English · 中文

start with the real crab-powered harnesses

github.com/code-yeongyu/lazycodex
github.com/Yeachan-Heo/gajae-code

加入 Discord： ultraworkers discord · gajae-code discord

[!IMPORTANT] Claw Code 在这里并不是一个严肃的生产级项目。 这个代码库更像是一个博物馆的展品，而不是一个产品推介。它是一个由螃蟹（crab）驱动的工件，由带爪子的 gajae（小龙虾）维持生命，由智能体清扫和贴标签，并根据上述的工具（harnesses）自动维护。

正如项目理念中所描述的，这并不旨在像普通产品代码库那样由人工操作。它是一个由智能体管理的展品 (agent-managed exhibit)：当螃蟹保持水箱运转时，工具会规划、执行、验证、标记并保存该工件。

如果你想要实际运行工作任务，请从 LazyCodex 或 Gajae-Code 开始。如果你想研究 Claw Code 时刻这个奇怪的小化石，请继续往下看。

有关这一理念背后更详细的公开解释，请参阅这里。

ultraworkers/claw-code · 使用指南 (Usage) · Rust 工作区 (Rust workspace) · 一致性 (Parity) · 路线图 (Roadmap) · 贡献指南 (Contributing) · 安全 (Security) · UltraWorkers Discord

Claw Code 是 claw CLI 智能体工具的公开 Rust 实现。 规范的实现位于 rust/，此代码库当前的事实来源是 ultraworkers/claw-code。

[!IMPORTANT] 首先请阅读 USAGE.md 以了解构建、认证、CLI、会话和一致性工具（parity-harness）工作流。关于文件提交/导航问题，请参阅 导航和文件上下文 (Navigation and file context)。关于本地兼容 OpenAI 的模型和离线技能设置，请参阅 本地兼容 OpenAI 提供商及技能设置 (Local OpenAI-compatible providers and skills setup)。Windows 用户可以跳转至以 PowerShell 为主的 Windows 安装和发布快速入门 (Windows install and release quickstart)。构建完成后，请首先使用 claw doctor 进行健康检查，查看 rust/README.md 获取 crate 级别的详细信息，阅读 PARITY.md 了解当前的 Rust 移植检查点，并查阅 docs/container.md 了解优先使用容器的工作流。

ACP / Zed 状态： claw-code 尚未发布 ACP/Zed 守护进程或 JSON-RPC 入口点。请运行 claw acp（或 claw --acp）查看当前状态，而不是从源代码布局中猜测；claw acp serve 目前仅作为可发现性的别名，返回状态并以退出码 0 结束，真正的 ACP 支持仍在 ROADMAP.md 中单独追踪。有关公开的 JSON 契约，请参阅 docs/g011-acp-json-rpc-status-contract.md。

当前代码库结构

• rust/ — 规范的 Rust 工作区和 claw CLI 二进制文件
• USAGE.md — 针对当前产品表面的面向任务的使用指南
• PARITY.md — Rust 移植一致性状态和迁移说明
• ROADMAP.md — 活跃的路线图和清理待办事项
• PHILOSOPHY.md — 项目意图和系统设计框架
• src/ + tests/ — 配套的 Python/参考工作区和审计辅助工具；不是主要的运行时表面

快速入门

[!NOTE] [!WARNING] cargo install claw-code 会安装错误的东西。 crates.io 上的 claw-code crate 是一个已废弃的存根（stub），它会放置 claw-code-deprecated.exe — 而不是 claw。运行它只会打印 "claw-code has been renamed to agent-code"。请勿使用 cargo install claw-code。 请从源码构建（本代码库）或安装上游二进制文件：

cargo install agent-code   # 上游二进制文件 — 安装为 'agent.exe' (Windows) / 'agent' (Unix)，而不是 'agent-code'

本代码库 (ultraworkers/claw-code) 仅支持从源码构建 — 请遵循以下步骤。

# 1. 克隆并构建
git clone https://github.com/ultraworkers/claw-code
cd claw-code/rust
cargo build --workspace

# 2. 设置您的 API 密钥（Anthropic API 密钥 — 不是 Claude 订阅）
export ANTHROPIC_API_KEY="sk-ant-..."

# 3. 验证所有配置是否正确
./target/debug/claw doctor

# 4. 运行提示词
./target/debug/claw prompt "say hello"

# 5. 启动交互式会话
./target/debug/claw

[!NOTE] Windows (PowerShell)： 二进制文件是 claw.exe，而不是 claw。使用 .\target\debug\claw.exe 或运行 cargo run -- prompt "say hello" 以跳过路径查找。

Windows 设置

PowerShell 是一种支持的 Windows 路径。 您可以使用任何适合您的终端 shell。Windows 上常见的入门问题是：

1. 首先安装 Rust — 从 https://rustup.rs/ 下载并运行安装程序。完成后关闭并重新打开终端。
2. 验证 Rust 是否在 PATH 中：

   cargo --version
   

   如果失败，请重新打开终端或运行 Rust 安装程序输出的 PATH 设置步骤，然后重试。
3. 克隆并构建（在 PowerShell、Git Bash 或 WSL 中均可）：

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

4. 运行（PowerShell — 注意 .exe 和反斜杠）：

   $env:ANTHROPIC_API_KEY = "sk-ant-..."
   .\target\debug\claw.exe prompt "say hello"
   

有关发布版的 ZIP、PATH 设置、提供商切换以及通知的冒烟测试，请参阅 docs/windows-install-release.md。

Git Bash / WSL 是可选的替代方案，而非必须。如果您更喜欢 bash 风格的路径（例如 /c/Users/you/... 而不是 C:\Users\you\...），Git Bash（随 Git for Windows 一起提供）效果很好。在 Git Bash 中，MINGW64 提示符是预期的正常现象 — 并不代表安装已损坏。

构建后操作：定位二进制文件并验证

在 claw-code/rust/ 中运行 cargo build --workspace 后，claw 二进制文件已构建，但不会自动安装到您的系统中。以下是定位文件和验证构建是否成功的方法。

二进制文件位置

cargo build --workspace 后，在 claw-code/rust/ 目录中：

Debug 构建（默认，编译较快）：

• macOS/Linux： rust/target/debug/claw
• Windows： rust/target/debug/claw.exe

Release 构建（已优化，编译较慢）：

• macOS/Linux： rust/target/release/claw
• Windows： rust/target/release/claw.exe

如果您运行 cargo build 时没有添加 --release，则二进制文件位于 debug/ 文件夹中。

验证构建是否成功

直接使用其路径测试二进制文件：

# macOS/Linux (debug 构建)
./rust/target/debug/claw --help
./rust/target/debug/claw doctor

# Windows PowerShell (debug 构建)
.\rust\target\debug\claw.exe --help
.\rust\target\debug\claw.exe doctor

无需实时凭据的 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

如果这些命令成功执行，说明构建正常工作。claw doctor 是您的首个健康检查工具 — 它会验证您的 API 密钥、模型访问权限和工具配置。

可选：添加到 PATH

如果您希望在任何目录下都不用输入完整路径即可运行 claw，请选择以下方法之一：

选项 1：符号链接 (macOS/Linux)

ln -s $(pwd)/rust/target/debug/claw /usr/local/bin/claw

然后重新加载 shell 并测试：

claw --help

选项 2：使用 cargo install (所有平台)

构建并安装到 Cargo 的默认位置（~/.cargo/bin/，通常已在 PATH 中）：

# 在 claw-code/rust/ 目录下
cargo install --path . --force

# 然后在任何地方都可以运行
claw --help

选项 3：更新 shell 配置文件 (bash/zsh)

将此行添加到 ~/.bashrc 或 ~/.zshrc：

export PATH="$(pwd)/rust/target/debug:$PATH"

重新加载 shell：

source ~/.bashrc  # 或 source ~/.zshrc
claw --help

故障排除

• "command not found: claw" — 二进制文件在 rust/target/debug/claw，但未在您的 PATH 中。请使用完整路径 ./rust/target/debug/claw 或按照上述方法进行软链接/安装。
• "permission denied" — 在 macOS/Linux 上，如果缺少可执行权限（罕见情况），您可能需要运行 chmod +x rust/target/debug/claw。
• Debug vs. release — 如果构建运行缓慢，说明您处于 debug 模式（默认）。在 cargo build 中添加 --release 以获得更快的运行时速度，但这会使构建本身花费 5-10 分钟。

[!NOTE] 认证： claw 需要一个 API 密钥 (ANTHROPIC_API_KEY, OPENAI_API_KEY 等) — 暂不支持 Claude 订阅登录作为认证途径。

在验证二进制文件可运行后，执行工作区测试套件：

cd rust
cargo test --workspace

文档地图

• USAGE.md — 快捷命令、认证、会话、配置、一致性工具
• docs/navigation-file-context.md — 终端导航、历史滚动记录、@path 文件上下文、附件以及安全秘钥指南
• docs/local-openai-compatible-providers.md — Ollama/llama.cpp/vLLM 设置、Claw 多提供商定位和本地技能安装检查
• docs/windows-install-release.md — PowerShell 为主的安装、发布工件、提供商切换和 Windows/WSL 通知冒烟测试路径
• rust/README.md — crate 地图、CLI 表面、功能特性、工作区布局
• PARITY.md — Rust 移植的一致性状态
• rust/MOCK_PARITY_HARNESS.md — 确定性模拟服务工具（mock-service harness）详细信息
• ROADMAP.md — 活跃的路线图和待清理的后台任务
• docs/g004-events-reports-contract.md — 面向消费者的 Stream 2 lane 事件/报告契约指南
• PHILOSOPHY.md — 该项目存在的原因以及它的运作方式
• CONTRIBUTING.md, SECURITY.md, SUPPORT.md 和 CODE_OF_CONDUCT.md — 贡献、漏洞报告、支持和社区政策
• LICENSE — 此代码库的 MIT 许可证

生态系统

Claw Code 是在开源环境下与更广泛的 UltraWorkers 工具链一起构建的：

• clawhip
• oh-my-openagent
• oh-my-claudecode
• oh-my-codex
• gajae-code
• UltraWorkers Discord

所有权 / 附属声明

• 本代码库不声明对原始 Claude Code 源代码拥有所有权。
• 本代码库不隶属于 Anthropic，未获得 Anthropic 的认可，也不由 Anthropic 维护。

---

中文翻译由 JasonYeYuhe 维护