English | 中文 | Français | Русский | हिन्दी | العربية | Português

ClawCodex

A production-oriented Python rebuild of Claude Code — real architecture, reliable CLI agent

Ported from the TypeScript reference implementation and extended with a Python-native runtime

🔥 Active Development • New Features Weekly 🔥

A 30-second session in the web UI (clawcodex web): ask for a feature, watch it read, edit, run the tests, and report. MP4 version

🤝🦞 Multi-Agent Teams

Persistent teammates, and one supervisor for every agent

New in v1.7.0: TeamCreate makes your session the leader. Named teammates stay alive between assignments, message each other and the leader, and pull work from a shared, dependency-aware task board — while one session-scoped supervisor admits, tracks and interrupts every subagent, foreground or background, and can pause new spawns for the whole session.

Background workers genuinely resume with their history under the same ID, a worker's pending permission prompt is withdrawn when it is interrupted, and worktree isolation runs in a real Git checkout or fails before the model runs. In-process teams, one per workspace — verified end to end with a scripted provider driving real query loops, tools and WebSocket connections, plus a live DeepSeek smoke run. Read the verification notes →

🏆 Terminal-Bench 2.1

80.9% on Claude Opus 5 — a top-tier open-source result

72 of 89 tasks solved (pass@1) on the verified 89-task suite. On the public leaderboard that slots around 3rd — behind Claude Code / Fable 5 (83.8%) and Codex / GPT-5.5 (83.1%), ahead of Claude Code on Opus 4.8 (78.9%).

ClawCodex — the open-source Python rebuild of Claude Code — run headless on claude-opus-5 at effort=xhigh. A single run (k=1) against the board's k=5 averages; benchmarked on main at #756. Fully reproducible from the open-source Harbor adapter. Read the full breakdown ↓

🌿✂️ /eco Token Compression

Same session, 80% fewer Bash-output tokens

Measured, not estimated: 27 real command outputs replayed through the production pipeline — 92,989 → 17,767 tokens (-80%). Failure summaries keep the error lines that matter; anything lossy is teed to disk, one tail away.

One toggle, deterministic filters — failure-focused test summaries, git/pip/npm ceremony stripping, log dedup, recoverable head-caps — guarded to be never worse than the raw rendering. Stacks with the DeepSeek prefix cache: the cache makes your stable prefix nearly free, /eco shrinks the fresh suffix every turn actually pays for. See the measured benchmark ↓

🐋🔥 DeepSeek Prefix Cache

Run long agentic coding sessions for pennies

Cache-hit input bills at $0.003 / 1M tokens — about 3,300× cheaper than Claude Fable 5 ($10 / 1M).

ClawCodex keeps your request prefix byte-stable, so DeepSeek's prompt cache covers your whole system + tools + history span across turns. The longer you code, the more you save.

deepseek-flash (DeepSeek-V4.1-Flash) off-peak, checked 2026-09-10. DeepSeek doubles every rate during peak hours (01:00–04:00 and 06:00–10:00 UTC, Mon–Fri) — still ~1,600× cheaper there. /cost follows the schedule.

🐜 --nano Mode

The pi-style minimal harness, built in

Full Terminal-Bench 2.1, same model, head-to-head with the pi harness (its own TB setup, vision+websearch matched): nano 64/89 and 63/89 in its two latest runs vs pi 63/89 — level on score, k=1 per run.

Six tools, a ~2K-token fixed payload (vs ~17K default), zero per-turn injections, /eco on. clawcodex --nano -p "<task>" ports the pi harness's edit ladder (multi-edit + fuzzy match), truncation guard, and compaction file-ledger — while non-nano behavior is unchanged, apart from a Bash fix every mode got: output is now drained while a command runs, so one that prints over ~64 KB no longer stalls until the timeout. docs/nano.md

⚡ Quick Install

One line — installs uv, Python 3.10+, and puts clawcodex on your PATH.

macOS / Linux / WSL / Git Bash:

curl -fsSL https://clawcodex.app/install.sh | bash

Windows (native PowerShell — no WSL needed):

irm https://clawcodex.app/install.ps1 | iex

Then configure a provider and start coding:

clawcodex login   # interactive provider + API key setup → ~/.clawcodex/config.json
clawcodex         # start it in any project — Full Access by default, /permissions to change
clawcodex web --build  # first run: build and start the Web UI at http://127.0.0.1:8081

Both installers ship the same clawcodex lifecycle helpers — doctor (diagnose your environment), verify (health-check the install), update, and uninstall — and are re-run-safe. To pass flags through the pipe: curl -fsSL https://clawcodex.app/install.sh | bash -s -- --dry-run on POSIX, or & ([scriptblock]::Create((irm https://clawcodex.app/install.ps1))) -DryRun on Windows. Windows prerequisite: Git for Windows — its Git Bash is what the shell tool runs commands with.

git clone https://github.com/agentforce314/clawcodex.git
cd clawcodex
python3 -m venv .venv && source .venv/bin/activate   # Python 3.10+
pip install -r requirements.txt

python -m src.cli login   # writes config to ~/.clawcodex/config.json

python -m src.cli   # start it (Full Access by default; /permissions to change)

The configuration file is saved at ~/.clawcodex/config.json. Minimal example:

{
  "default_provider": "deepseek",
  "providers": {
    "deepseek": {
      "api_key": "xxx-xxx",
      "base_url": "https://api.deepseek.com",
      "default_model": "deepseek-flash"
    }
  },
  "env": {
    "TAVILY_API_KEY": "tvly-YOUR-TAVILY-API-KEY"
  }
}

Note: TAVILY_API_KEY is required for the WebSearch tool — get a key at tavily.com.

The session, settings, and env blocks are optional — sensible defaults apply when they're omitted. See Configure for the full structure.

📰 News

• 2026-09-23 (v1.7.0): The multi-agent system, rebuilt — persistent teams, workers that really resume, and one supervisor for every agent (#915, #950) — ClawCodex used to spawn subagents down two paths that never met, and only one of them was observable. A foreground delegation registered nowhere, so nothing could list or stop it; the TUI's agents overlay called three RPCs that had no backend; a follow-up sent to a finished background worker flipped it back to running without ever starting a model loop; and the team tools existed with no production path that actually ran a teammate. v1.7.0 rebuilds that layer. One supervisor (#915, #950): a session-scoped supervisor admits every worker — foreground, background, team and workflow — behind two backstops (CLAWCODEX_MAX_CONCURRENT_AGENTS, default 32; CLAWCODEX_MAX_AGENT_DEPTH, default 3), with live status, per-agent interrupt and a session-wide pause on new spawns in the TUI's agents overlay and the web client's subagent list (#933); a refused spawn comes back as a tool error the model can act on. Persistent teams (#950): TeamCreate makes your session the leader; each named Agent call adds a teammate that stays alive between assignments with its context intact; SendMessage routes findings to a named peer or to the leader; a shared, locked task board hands out work in dependency order; plan approvals and shutdowns follow a matched request/response protocol; and interrupting a worker withdraws its pending permission prompt. Lifecycles that hold (#950): resume reloads the worker's history under the same ID, a correction accepted while it was finishing is no longer left unread, notifications reach the session and parent that own them, isolation runs in a real Git worktree or fails before the model runs, and ending a session interrupts every worker it owns and waits a bounded time for them to stop. Verified by end-to-end suites that drive real query loops, tools, worktrees and WebSocket connections against a scripted provider, plus a live DeepSeek smoke run — and scoped plainly: teams are in-process (no tmux/iTerm pane or remote backends), one per workspace, a worker resumes only within the session that started it, and there is no automatic crash recovery (verification notes). Also in v1.7.0: clawcodex --nano, the pi-style minimal harness — a ≈2K-token fixed payload instead of ≈17K, and level with the pi harness on the ful