ClawCodex

<div align="center">

**English** | [中文](docs/i18n/README_ZH.md) | [Français](docs/i18n/README_FR.md) | [Русский](docs/i18n/README_RU.md) | [हिन्दी](docs/i18n/README_HI.md) | [العربية](docs/i18n/README_AR.md) | [Português](docs/i18n/README_PT.md)

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

***

[![GitHub stars](https://img.shields.io/github/stars/agentforce314/clawcodex?style=for-the-badge&logo=github&color=yellow)](https://github.com/agentforce314/clawcodex/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/agentforce314/clawcodex?style=for-the-badge&logo=github&color=blue)](https://github.com/agentforce314/clawcodex/network/members)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)


**🔥 Active Development • New Features Weekly 🔥**

![ClawCodex Screenshot](assets/clawcodex-screenshot-1.png)

</div>

***

<div align="center">

# 🌿✂️ /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](#-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 ↓](#eco-benchmark)**

</div>

***

<div align="center">

# 🐋🔥 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.**

</div>

***

## ⚡ Quick Install

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

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

Then configure a provider and start coding:

```bash
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`.

<details>
<summary><b>Or install manually from source</b></summary>

```bash
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
```

</details>

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

```json
{
  "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](https://tavily.com).

The `session`, `settings`, and `env` blocks are optional — sensible defaults apply when they're omitted. See [Configure](#configure) for the full structure.

***

## 📰 News

- **2026-07-13:** **`/eco` token compression — -80% Bash-output tokens, measured, now a headline (#708, #712)** — a new session toggle compresses the model-bound rendering of every Bash result with deterministic filters ported from [RTK](https://github.com/rtk-ai/rtk)'s method set: failure-focused test summaries (kept error lines are never rewritten), `git`/`pip`/`npm` ceremony stripping, log dedup with `[×N]` counts, and a recoverable head-cap — all behind a **never-worse** guard, with every lossy compression teeing the full output to disk behind a runnable recovery hint (#708). A reproducible benchmark (`eval/eco/`) replays 27 real command outputs through the exact production pipeline and counts real tokenizer tokens: **92,989 → 17,767 (-80%)** corpus-wide, -88% on filter hits, plus an honestly conservative r

... (truncated)