ClawCodex: a Python rebuild of Claude Code with /eco token compression and a DeepSeek prefix cache

The problem ClawCodex targets: agent cost and an opaque TypeScript core

Two costs drive an agentic coding session. The first is tokens: every Bash command, test run and log dump lands in the context window, and the model pays to read it again on the next turn. The second is control: when the agent is a closed binary, you cannot change how it truncates output or which tools it exposes.

ClawCodex answers both by being a full Python rebuild of Claude Code, ported from the TypeScript reference implementation and extended with what the README calls a Python-native runtime. The repository holds 270K lines of Python according to its description, with separate `ui-tui/`, `ui-desktop/` and `ui-web/` trees. The intended reader is an engineer who wants to read the agent's source, swap providers, and pay less per turn. The README's headline claims are 80.9% on Terminal-Bench 2.1 with `claude-opus-5` at `effort=xhigh`, and up to 200X cost saving, the latter driven by provider choice and cache behaviour rather than by the code alone.

How /eco compresses Bash output, and what the prefix cache depends on

`/eco` is a deterministic filter layer between a tool's raw output and the message history. The README describes failure-focused test summaries, stripping of `git`, `pip` and `npm` ceremony, log deduplication, and recoverable head caps. The measured figure given is 27 real command outputs replayed through the production pipeline, 92,989 tokens down to 17,767, an 80% reduction. Two design details matter more than the number. Anything lossy is teed to disk, so the full output is one `tail` away rather than gone. And the filters are guarded to be never worse than the raw rendering, which is the constraint that keeps a compression pass from silently deleting the error line you needed.

The second mechanism sits below the agent, in the provider's prompt cache. DeepSeek bills cache-hit input at $0.022 per 1M tokens according to the README, against $10 per 1M for Claude Fable 5, with the caveat that DeepSeek doubles every rate during peak hours (01:00-04:00 and 06:00-10:00 UTC, Monday to Friday). For the cache to hit, the request prefix has to stay byte-stable across turns, so the agent keeps `system + tools + history` unchanged and lets only the suffix grow. That is a real architectural constraint, not a toggle: any per-turn injection into the system prompt destroys the hit rate. The README notes `--nano` mode has zero per-turn injections for exactly this reason.

Installing ClawCodex and running a first session

The README gives a one-line installer for macOS, Linux, WSL and Git Bash. It installs `uv`, Python 3.10+ and puts `clawcodex` on your PATH. On Windows there is a separate PowerShell path that does not require WSL.

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

After that, configure a provider. `clawcodex login` runs an interactive provider and API key setup and writes to `~/.clawcodex/config.json`. The same file can be edited by hand; the README's minimal example uses DeepSeek and includes a Tavily key for the WebSearch tool.

{
  "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"
  }
}

Running `clawcodex` with no arguments starts the agent in the current project. The README states it starts with Full Access by default and that `/permissions` changes that. You should expect the agent to begin reading and editing files immediately, which is why the permissions default is the first thing to check. Two lifecycle helpers ship with both installers: `clawcodex doctor` diagnoses the environment and `clawcodex verify` health-checks the install. The installer is re-run-safe, and flags pass through the pipe with `bash -s -- --dry-run` on POSIX.

If you prefer source, the README documents a manual path: clone the repository, create a virtual environment on Python 3.10+, install `requirements.txt`, then run `python -m src.cli login` and `python -m src.cli`. Note that `clawcodex` and `python -m src.cli` are two entry points into the same code.

Where ClawCodex is the wrong tool, and the dependency caps it carries

The packaging metadata classifies the project as Development Status 3, Alpha. That is the project's own label, and it should shape how you treat version upgrades. The changelog shows v1.4.0, v1.5.0 and v1.6.0 landing within thirteen days in August 2026, and the README's own banner promises new features weekly. Fast movement plus an Alpha classifier means a pinned version is the safer deployment, and the README does not document a rollback or downgrade procedure.

The dependency file is more revealing than the feature list. Both `anthropic` and `openai` are capped below their next major version, and both comments give the same reason: the 1.0.0 and 3.0.0 releases moved the SDKs onto `httpx2`, which rejects a passed `http_client=httpx.Client(...)` and, in the OpenAI case, silently bypasses the httpx layer the project hooks. The `mcp` package is capped below 2.0 because 2.0.0 removed `mcp.client.websocket`, which `src/services/mcp/transport.py` imports. These are honest notes, but they also mean the project is coupled to SDK internals and will need migration work when those caps lift.

A second limitation is scope. The README ties the strongest cost numbers to DeepSeek. If your organisation requires Anthropic or OpenAI models, the prefix-cache argument does not transfer, and you are left with `/eco` and the agent architecture. Third, WebSearch depends on `TAVILY_API_KEY`; without it that tool is unavailable. Finally, the Windows installer needs Git for Windows, because Git Bash is what the shell tool runs commands with.

How ClawCodex differs from Claude Code and from a minimal harness

The obvious alternative is Claude Code itself, the TypeScript implementation ClawCodex was ported from. The difference is not capability but access. Claude Code is a distributed product; ClawCodex is a Python tree you can read, patch and point at any provider, with the README's provider list covering Anthropic, OpenAI, DeepSeek and GLM. The README's own benchmark table puts Claude Code at 83.8% on Terminal-Bench 2.1 and ClawCodex at 80.9%, so the rebuild is not claiming parity. If you want the highest score and do not need to modify the agent, the original is the safer pick.

The second comparison is with minimal harnesses. The README compares `--nano` mode against the pi harness on the same 89-task suite: 64/89 (71.9%) at $1.31 versus 63/89 (70.8%) at $2.01. Nano mode uses six tools and a roughly 2K-token fixed payload against about 16K in the default configuration, with `/eco` on. The design point is that the default configuration carries more tooling and a larger fixed payload, and nano strips both. That is a genuine trade-off rather than a strict improvement: fewer tools means fewer capabilities available to the model on a task that needs them.

Licence, upgrade cost and what the repository does not settle

The licence is MIT, declared both in `pyproject.toml` and in the repository's `LICENSE` file, with `license-files` pointing at it. MIT is permissive, so redistribution and modification are permitted subject to the licence text. That is a statement about the licence, not legal advice; if you ship ClawCodex inside a product, read the MIT terms and check the licences of the dependencies, which are separate packages with their own terms.

Upgrade cost is where the material is thinnest. The README documents `clawcodex update` as a lifecycle helper, and the installers are re-run-safe, but there is no documented migration path between minor versions and no stated compatibility policy for `~/.clawcodex/config.json`. The config file is JSON with `session`, `settings` and `env` blocks described as optional, so hand-edited files are expected. Given three releases in thirteen days and an Alpha classifier, budget for reading the changelog before each bump rather than assuming the config schema is frozen. The last push to the repository was on 2026-08-15.

Editorial conclusion

Adopt ClawCodex if you want a Python-native agent you can read and patch, and you are willing to run a project classified as Alpha. Skip it if you need a stable release line or a documented upgrade path between minor versions, because the README describes an install script, not a migration story. Before committing, run clawcodex doctor and clawcodex verify on the target machine, then check /cost against your own provider rates, since the README's cache figures are tied to deepseek-v4-pro off-peak pricing checked on 2026-08-25.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes