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 🔥

---

🐋🔥 DeepSeek Prefix Cache

Run long agentic coding sessions for pennies

Cache-hit input bills at ~$0.0435 / 1M tokens — about 230× 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.

---

⚡ Quick Install

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

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

Then configure a provider and start coding:

clawcodex login   # interactive provider + API key setup → ~/.clawcodex/config.json
clawcodex --dangerously-skip-permissions         # start the REPL in any project

The installer also ships clawcodex lifecycle helpers — doctor (diagnose your environment), verify (health-check the install), update, and uninstall. It is re-run-safe and works on macOS, Linux, and WSL. To pass flags through the pipe, use curl -fsSL https://clawcodex.app/install.sh | bash -s -- --dry-run.

Or install manually from source

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 --dangerously-skip-permissions   # start the REPL

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-v4-pro"
    }
  },
  "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-06-30 (v0.7.0): ClawCodex v0.7.0 — TUI auto-theming, faithful inline rendering & a Claude-Code-style tool trail — the Ink TUI now detects your terminal's background color (OSC 11) on startup and selects the light/dark theme to match, so text stays readable on any terminal with no env var needed (#577). Inline mode renders truly inline like Claude Code: no screen wipe on launch, and no overlap with prior terminal output on startup or with the returning shell prompt on exit (#573, #575). The tool trail reads Claude-style — workspace-relative paths (Read(src/foo.ts)), Grep(pattern) labels, and a Read N lines result collapse (#574) — and the banner gains a 🦞 mascot with brighter secondary text on dark themes (#576).
• 2026-06-24 (v0.6.0): ClawCodex v0.6.0 — interactive TUI REPL parity — a batch of input ports brings the Python REPL to parity with the ink reference: a working slash-command menu (execute / complete / filter like the ink REPL), the sparkle spinner with a live token + elapsed busy row, context-aware prompt footer hints (interrupt / bash / grammar), the ? shortcuts help panel, an @ file-mention dropdown with in-place splice, double-press Ctrl+C / Ctrl+D to exit, Ctrl+R history search + double-Esc clear-draft, a [Pasted text #N +K lines] large-paste placeholder, and the completed command queue (drain queued prompts + dim preview). Login docs now list all 25 providers (#383).
• 2026-06-23: One-click installer — curl -fsSL https://clawcodex.app/install.sh | bash installs uv (no sudo), provisions Python 3.10+, clones to ~/.clawcodex, creates a lock-pinned venv, and registers clawcodex on PATH; ships status / doctor / verify / update / uninstall subcommands, is safe to re-run, and works on macOS / Linux / WSL.
• 2026-06-21: 18 new LLM providers — the registry grows 7 → 25 (#377) — a data-driven ProviderSpec registry adds 18 OpenAI-compatible backends (nvidia-nim, fireworks, together, moonshot/Kimi, novita, siliconflow, deepinfra, stepfun, arcee, huggingface, volcengine, xiaomi-mimo, atlascloud, wanjie-ark, plus local ollama / vllm / sglang) alongside the hand-written providers; alias-aware config resolution, standard env-var key fallback (e.g. TOGETHER_API_KEY), and keyless local servers.
• 2026-06-18: DeepSeek prefix-cache exploitation — a HUGE token-cost win (#363) — ClawCodex now keeps its request prefix byte-stable across turns so DeepSeek's automatic prompt-prefix cache covers the entire system + tools + history span. Per-request-volatile sections (env, the mutable MEMORY.md body, plan-mode, etc.) are relocated to a trailing <system-reminder> after the conversation history, so the cached prefix never breaks even when memory/env change. We also register DeepSeek's 1M-token context window, map its prompt-cache usage onto the Anthropic cache_read_input_tokens convention, and surface a per-model prompt-cache hit-rate + cost in /cost. Why this is enormous — the token economics: Claude Fable 5 runs $10 / $50 per 1M input/output tokens, while DeepSeek-V4-Pro is just $0.435 / $0.87 — already ~23× cheaper on input and ~57× cheaper on output. And because cache-hit input is billed at only 10% of the normal input rate, the long, context-heavy sessions that agentic coding actually produces pay just ~$0.0435 per 1M input tokens — roughly 230× cheaper than Fable 5 input. The token efficiency ClawCodex unlocks here is HUGE. Everything is gated to the deepseek provider — every other provider's request is byte-for-byte unchanged. Follow-up: truncated tool-call argument JSON is now best-effort recovered in the shared OpenAI-compatible layer, so an interrupted DeepSeek stream keeps its partial tool args instead of dropping them to {} (#364).
• 2026-06-16: Z.ai GLM-5.2 support (#343) — new zai provider for Z.ai's OpenAI-compatible GLM Coding Plan (https://api.z.ai/api/coding/paas/v4), shipping GLM-5.1 and the GLM-5.2 preview; GLM-5.2 delivers coding capability comparable to Claude Opus 4.7. First app built end-to-end with GLM-5.2 — a FIFA World Cup 2026 intro page (animated hero + live countdown, three host nations, 16 stadiums, tournament format, and record-breaking facts).
• 2026-06-11: Codebase stats — Total Python files: 1,093 files; Total Lines of Python Code: 233,520 lines (up from 213,777 lines on 2026-05-29; ~+19.7k lines from the interactive command-system batch, the dynamic workflow engine + /deep-research, and the Tavily web-tooling refresh).
• 2026-06-10 to 2026-06-11: Dynamic workflow engine + /deep-research (#262–#264, #266–#271) — Python workflow engine core (agent()/parallel()/pipeline()/phase(), journaling, resume) wired end-to-end: Workflow tool, /workflows TUI dialog + status-line pill, per-agent retry, worktree isolation, result delivery, and the bundled /deep-research harness registered as a slash command. Reliability: LLM read timeout applied centrally to all openai-compatible providers (#269), parallel agents no longer serialize on the event loop (#270), and the deep-research synthesize step forbids tools so the report-writer can't loop (#271). Follow-ups: workflow max-turns cap fix (#272), deep-research verdict-enum fix (#273), rich /workflows live monitor with phase progress + per-agent stats (#287).
• 2026-06-10: Web tooling refresh (#265) — dead DuckDuckGo scraping replaced with a Tavily-backed WebSearch plus config-backed secrets storage; WebFetch rebuilt with deterministic markdown/text/html extraction (borrowed from opencode).
• 2026-05-30 to 2026-06-09: Interactive command-system parity (#230–#261) — interactive ports of /theme, /effort, /model, /logo, /mcp, /tasks, /diff, /export, /output-style, /statusline, /release-notes, /copy, /vim, /memory, /stickers, and /rename, built on a new prompt-text primitive and interactive command bridge; skill registration and model tool-exposure wiring; the session-persistence producer (SessionPersister + agent-bridge wiring); plus extended thinking support (#249) and a model error-swallow fix (#250).
• 2026-05-29: Codebase stats — Total Python files: 977 files; Total Lines of Python Code: 213,777 lines (up from 183,768 lines on 2026-05-21; ~+30k lines from the remote-bridge parity port (phases 0–18) plus the /buddy companion subsystem and the CLI transport layer).

📚 Older items have moved to the full News archive.

---

🎯 Why ClawCodex?

ClawCodex is a production-oriented Python rebuild of Claude Code, ported from the real TypeScript architecture and shipped as a working CLI agent, not just a source dump.

• Real Agent Runtime — tool-calling loop, streaming REPL, session history, and multi-turn execution
• High-Fidelity Port — keeps the original Claude Code architecture while adapting it to idiomatic Python
• Built to Hack On — readable Python codebase, rich tests, and markdown-driven skill extensibility
• Multi-LLM providers — the biggest step forward vs. upstream: Claude Code is built around Claude-series models only; ClawCodex is dedicated to wiring in all major LLM providers so you can choose the most flexible and cost-effective stack for agentic coding

A real Claude Code-style terminal workflow in Python: stream replies, call tools, fetch context, and extend behavior with skills.

🚀 Try it now! Fork it, modify it, make it yours! Pull requests welcome!

---

🏆 SWE-bench Verified — clawcodex outperforms openclaude on the same model

On the full SWE-bench Verified split (499 instances, the public agent-coding leaderboard), both agents driven by Gemini 2.5 Pro under our standardized harness:

Agent	Resolved	Unresolved	Error
clawcodex	291 / 499 (58.2%)	124	84
openclaude	265 / 499 (53.0%)	144	90

• ✅ Both solved: 241    🟢 Only clawcodex: 50    🔵 Only openclaude: 24    ❌ Neither: 184

Reproduce locally — see eval/README.md for the full workflow (cumulative batching, --predict-workers N, --capture-traces).

---

⭐ Star History

View star history on star-history.com

✨ Features

Streaming Agent Experience

>>> /stream on
>>> Explain tests/test_agent_loop.py
[streaming answer...]
• Read (tests/test_agent_loop.py) running...
  ↳ lines 1-180
>>> /render-last

• True API streaming for direct replies plus richer streaming during tool-driven agent loops
• Built-in /stream toggle for live output and /render-last for clean Markdown re-rendering on demand
• Designed for real terminal demos: streaming text, visible tool activity, and stable fallback behavior

Programmable Skill Runtime

---
description: Explain code with diagrams and analogies
allowed-tools:
  - Read
  - Grep
  - Glob
arguments: [path]
---

Explain the code in $path. Start with an analogy, then draw a diagram.

• Markdown-based SKILL.md slash commands
• Supports project skills, user skills, named arguments, and tool limits

Multi-Provider Support

ClawCodex’s main advantage is multi-provider support: while Claude Code targets Claude models, we aim to support every major LLM provider behind the same agent runtime—so you can swap vendors, regions, and price tiers without giving up tools, skills, or the coding loop. That flexibility is what makes agentic coding practical at scale.

providers = [
    # Native / bespoke wire formats
    "anthropic", "minimax", "deepseek", "zai", "openrouter", "openai", "gemini",
    # OpenAI-compatible vendors
    "nvidia-nim", "atlascloud", "wanjie-ark", "volcengine", "xiaomi-mimo",
    "novita", "fireworks", "siliconflow", "siliconflow-cn", "arcee", "moonshot",
    "huggingface", "together", "stepfun", "deepinfra",
    # Local servers (no API key required)
    "ollama", "vllm", "sglang",
]  # 25 providers; aliases like `nim`, `kimi`, `hf` resolve automatically

Any new OpenAI-compatible vendor is a one-row addition to src/providers/openai_compatible_specs.py (base URL + default model + API-key env vars). API keys resolve from config or the provider's standard env var (e.g. TOGETHER_API_KEY, `MOO