A working agent, not a source dump
A genuine tool-calling loop, a streaming REPL, session history, and multi-turn execution. Ported from the real Claude Code TypeScript architecture and shipped as a CLI you actually run.
80.9% on Terminal-Bench 2.1 · open source · multi-provider
A token-efficient coding agent for your terminal, on any model.
ClawCodex is a token-efficient Python rebuild of Claude Code — 230K lines of pure Python. A genuine tool-calling loop, a streaming REPL, skills, and one runtime in front of Anthropic, OpenAI, Z.ai GLM, MiniMax, OpenRouter, and DeepSeek, where prefix-cache reuse makes long DeepSeek sessions over 200× cheaper to run.
Mission for this build
Keep the real Claude Code architecture, but make it Python-native and open to every provider. Stream replies, call tools, persist sessions, and let you choose the most flexible, cost-effective model stack for agentic coding. Now 1.0; shipping weekly.
30+
tools
files, bash, web, agents, MCP
25
providers
one runtime, swap any time
80.9%
Terminal-Bench 2.1
on Opus 5 · k=1, ≈3rd
200×
cost saving
token-efficient on DeepSeek
Section 01 · why
A model writes text. An agent leaves consequences.
ClawCodex puts a real runtime around the model: a working loop, every provider, and code you can read and extend.
One runtime in front of every model
Claude Code targets Claude models only. ClawCodex puts Anthropic, OpenAI, Z.ai GLM, MiniMax, OpenRouter, and DeepSeek behind the same loop — so you swap vendor, region, and price tier without giving up tools or skills.
Readable Python you can extend
Idiomatic Python with full type hints, real test suites, and markdown-driven SKILL.md extensibility. Fork it, add a tool or a skill, and make it yours. MIT licensed.
Section 02 · what's inside
The full surface, in your terminal.
Streaming, skills, permissions, sessions, MCP, and a scriptable headless mode — the same loop whichever model you point it at.
Token-efficient on DeepSeek
ClawCodex keeps the request prefix byte-stable so DeepSeek's prompt cache covers your whole system + tools + history span. Cache-hit input bills at about $0.0435 per 1M tokens, over 200× cheaper than Claude Fable 5, so long agentic sessions cost pennies. The longer you code, the more you save.
Streaming agent experience
True API streaming for direct replies plus richer streaming during tool-driven loops. Toggle live output with /stream and re-render clean Markdown with /render-last.
Programmable skill runtime
Markdown-based SKILL.md slash commands with named arguments and per-skill tool limits. Project skills and user skills, loaded from .clawcodex/skills.
REPL by default, TUI on demand
An inline prompt_toolkit + Rich REPL with history, tab completion, and multiline input. Launch the Textual TUI any time with clawcodex --tui or /tui.
Permission modes
Plan (read-only), acceptEdits, dontAsk, and an explicit bypass for sandboxes. The REPL, TUI, and headless -p mode all honor the same gates.
Sessions you can resume
Save and reload conversations locally. auto_save writes each session; max_history caps retained turns. Everything stays on your machine.
MCP + hooks
Model Context Protocol tools and resources, plus pre/post tool-use lifecycle hooks for shell, prompt, agent, and HTTP automation.
Scriptable headless mode
Run -p for one-shot prompts, with --output-format json or stream-json for pipes, CI, and agent-to-agent workflows.
Image handling
A TS-parity Read pipeline sniffs magic bytes and resizes to API limits. @-mention an image to inline it, with Anthropic-to-OpenAI block translation for vision-capable backends.
Section 03 · any provider
One runtime in front of every model.
Swap vendor, region, and price tier without giving up tools or skills. All 25 providers ship today.
DeepSeek
default · prefix cache
Anthropic
Claude
OpenAI
GPT-5.4
Gemini
Google · 2.5 Pro
Z.ai GLM
GLM-5.1 / 5.2
MiniMax
MiniMax-M2.7
OpenRouter
multi-vendor proxy
NVIDIA NIM
Together AI
Fireworks AI
Novita AI
SiliconFlow
SiliconFlow (China)
Moonshot / Kimi
DeepInfra
Hugging Face
Volcengine Ark
StepFun
Arcee AI
AtlasCloud
Xiaomi MiMo
Wanjie Ark
Ollama
local · no key
vLLM
local · no key
SGLang
local · no key
Seven native integrations (DeepSeek, Anthropic, OpenAI, Gemini, Z.ai GLM, MiniMax, OpenRouter) plus an OpenAI-compatible gateway registry and local servers that need no key — 25 in all. Add any other OpenAI-compatible endpoint with a custom base_url; keys resolve from config or the vendor's standard env var (e.g. TOGETHER_API_KEY).
# point a single run at a different backend
clawcodex --provider deepseek --model deepseek-v4-pro
clawcodex --provider zai --model glm-5.2 -p "refactor utils.py"
Section 04 · how it works
A reviewable line from prompt to patch.
Read code, call tools behind permission gates, leave real evidence, and resume across sessions.
Prompt
You type in the REPL or pipe a prompt with -p. Plan mode is read-only by default.
Stream
The selected provider streams the reply; tool calls overlap with the stream.
Tools
Reads, edits, bash, and web run behind permission gates, leaving real evidence.
Resume
Results feed the next turn. Sessions save locally so long work survives.
under the hood · six abstractions
Query loop
The heartbeat that orchestrates model calls and tool execution.
Tool system
30+ tools: read files, run bash, search the web, drive sub-agents and MCP.
Tasks
Background workflows and agent orchestration, journaled and resumable.
Two-tier state
A bootstrap layer and an app layer, kept independent by design.
Memory
Relevance scanning over project, user, and team CLAUDE.md files.
Hooks
Lifecycle events with shell, prompt, agent, and HTTP executors.
Section 05 · swe-bench verified
clawcodex beats openclaude on the same model.
Full SWE-bench Verified split (499 instances), both agents driven by Gemini 2.5 Pro under one standardized harness.
241 Both solved
50 Only clawcodex
24 Only openclaude
184 Neither
Section 06 · proof
Every demo was built by ClawCodex itself.
Same CLI you just installed, same agent loop, same tools. No hand-edits.
CRM app
A mini CRM with contacts, deals, a dashboard, and a full test suite.
demos/crm-app
LinkedIn-style feed
Profile, network, jobs, and messaging in a familiar feed layout.
demos/linkedin-app
Minecraft sandbox
A browser voxel sandbox with terrain, mining, a HUD, and player controls.
demos/minecraft-app
World Cup 2026 intro
Animated hero, live countdown, host nations, and 16 stadiums. Built with GLM-5.2.
demos/wc26-intro
Section 07 · new in v1.4.0
Shipping weekly.
v1.4.0's headline is fusion models: pair a text-only reasoning model with a vision-capable one and it can finally read screenshots, diagrams and code images. It also adds GPT-5.6, four more OpenAI-compatible providers, a three-level permissions picker, and a round of cost-accounting fixes that stop cached tokens being billed at the full input rate.
models#771, #787
Fusion models — give a text-only model vision
Several strong reasoning models cannot see images at all: deepseek-v4-pro rejects an image content block outright, so pasting a screenshot ended the turn. A fusion model pairs that base with a vision-capable one — every image is described first, and the base model reads the description. Saved with /fusion, it then behaves like a normal model in the picker, as --model, in -p, and across restarts. Verified on Terminal-Bench 2.1's code-from-image task, which requires transcribing handwritten pseudocode from a PNG.
models#773, #783, #784
GPT-5.6 and four more providers
GPT-5.6 Sol, Terra and Luna are registered, and groq, cerebras, baseten and xai join the OpenAI-compatible registry — 30 providers now. The OpenAI provider also picks its wire protocol from the model rather than the auth mode, which is what makes gpt-5.6-luna usable on an API key at all.
permissions#768
/mode becomes /permissions, with Full Access by default
A three-option picker — ask for approval, approve for the session, or full access — replaces the old mode command, which stays as an alias.
fix#785, #786
Cached tokens were billed at the full input rate
prompt_tokens includes tokens served from the cache, and the cached count was being dropped, so a heavily-cached turn over-reported its cost several-fold. Both wires now split cache reads out. The same work surfaced that OpenRouter's streamed reasoning was discarded entirely.
fix#777–#782
Headless runs no longer report a cut-short run as success
A loop-guard kill, a plan-mode trap and an exhausted turn budget all surfaced as subtype: success — so /goal treated them as evidence of progress and re-ran on cancels and errors.
join in
A small project. Your patch matters.
No CLA. No sponsor lockouts. Issues triaged in the open, releases cut from main, and the maintainer reads everything. Bring a real test and prose that tells the reviewer what you were thinking.