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 🔥

🌿✂️ /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.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.

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-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'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 recompute of RTK's own 30-minute-session model (-19% under their averaged assumptions — real sessions are fat-tailed) (#712). Full tables: the /eco section and eval/eco/results/.
• 2026-07-12 (v1.1.0): ClawCodex v1.1.0 — run OpenAI and Claude models on your subscription, not metered API billing — the headline of 1.1.0 is subscription auth for the two biggest model families, so you can point ClawCodex at a plan you already pay for. Sign in with ChatGPT (#698): clawcodex login → openai → subscription (browser, device-code, or import from an existing Codex CLI login) routes requests through the ChatGPT Codex backend's Responses API — gpt-5.5, gpt-5.4, gpt-5.4-mini, and gpt-5.3-codex-spark on your Plus/Pro allowance, with encrypted-reasoning replay across turns and $0 metered cost. Claude Pro/Max (#697): clawcodex login → anthropic → subscription connects a Claude subscription via OAuth (PKCE) with automatic token refresh and the same $0 accounting; follow-ups repaired the login after Anthropic moved its OAuth endpoints to platform.claude.com (#702) and stopped sending adaptive thinking to models that don't support it (#699). A configured API key always wins, and subscription usage reports billing_mode: subscription. More models: a Meta (api.meta.ai) provider with the 1M-context muse-spark-1.1 reasoning model (#692) and refreshed MiniMax parameters (#696). Workflow & TUI: /plan mode with implicit plan-mode entry/exit (#676), --worktree/-w session isolation for parallel runs in separate git worktrees (#672), the /memory picker + $EDITOR spawn (#693), config/state directories rebranded .claude → .clawcodex with a one-time migration (#678), /logo startup color schemes (#677), plus TUI polish — Tab accepts the suggested placeholder (#690), past inputs get the Claude-Code highlight band (#691), clickable agent URLs (#694), and a per-terminal link-open affordance (#701). Quality: semantic tool-input coercion with parity validation errors (#700) and looser, Claude-Code-faithful permission granting (#673).
• 2026-07-07: /loop scheduled tasks now actually fire — full port of Claude Code's session-scoped scheduler (#680) — the bundled /loop skill finally has a real engine behind it: a new src/scheduled_tasks module parses standard 5-field cron expressions and fires due prompts between turns from the agent-server's idle poll. CronCreate/CronList/CronDelete register real firing jobs (8-char IDs, 50-job cap, deterministic jitter, 7-day recurring expiry with one final fire), and the new ScheduleWakeup tool drives self-paced /loop mode — the model picks each next delay (1 min–1 hr), stop: true ends the loop, and a ~20-minute fallback wakeup catches iterations that forget to reschedule. Typed skill slash commands now reach the backend (new skill_command control), so /loop 5m check ci works from the composer with completion + argument hint; the TUI shows a live countdown indicator (⟳ loop wakeup in 2m 14s · ⏰ 1 scheduled) and Esc while idle stops a waiting loop. /clear drops session tasks, --resume restores unexpired ones, CLAWCODEX_DISABLE_CRON=1 disables the scheduler. 117 new tests; verified live over stdio NDJSON and a real PTY TUI drive (typed dispatch → CronCreate → a real wakeup fire between turns → Esc-stop).
• 2026-07-07: Bounded the ESC-cancel chunk queue in OpenAI-compatible streaming (#278) — OpenAICompatibleProvider.chat_stream_response's worker-thread queue (added in #148) was an unbounded queue.Queue. A non-graceful disconnect from a proxy that keeps sending bytes after ESC (and never closes the SDK iterator) let the orphaned worker thread accumulate chunks in memory indefinitely. The queue is now capped at 64 chunks, so put() blocks the worker once full instead of growing without bound.
• 2026-07-06 (v1.0.0): ClawCodex v1.0.0 — the 1.0 release: goal-directed autonomy, hooks & MCP wired for production, and a hardened permission system — 86 commits since v0.7.0 (#580–#668) finish wiring the big subsystems end-to-end and graduate ClawCodex to 1.0. Goal-directed autonomy: the /goal + /subgoal completion-condition loop keeps the agent working until an LLM judge confirms the goal is actually met (#664), the new Monitor tool streams long-running shell output with backpressure (#665), background-bash completion notifications (#663), coordinator mode wired end-to-end on the live paths (#634), and /advisor token-efficient worker/reviewer pairing restored on the Ink TUI (#668). Hooks live in production: configured hooks now actually fire — bootstrap Hooks abstraction (#583), UserPromptSubmit (#597), multi-scope + lifecycle hooks (#595), if pre-filters (#643), PreToolUse permissionDecision (#655), PermissionRequest hooks at the ask seam (#637), MCP elicitation hooks (#659), and teammate TaskCompleted / TeammateIdle stop hooks (#642). MCP completion: OAuth server auth via the /mcp flow (#662), live tools/list_changed refresh (#598, #604), server instructions injected into the system prompt (#654), and clawcodex mcp serve re-exposes ClawCodex tools as an MCP stdio server (#635). Permission hardening: readable approval boxes with broadenable, persistent session grants (#608–#611), compound-command permission parity (#622), Bash normalization hardening (#626), disableBypassPermissionsMode lockdown (#660), an honest refuse-to-start unsandboxed guard (#658), subprocess secret-scrubbing (#650), and a flag-gated LLM security-classifier lane for auto mode (#589). TUI maturity: faithful Claude Code look & feel — diff rendering, tool-call transcript, task list, composer + permission-mode badge, busy line (#612–#616) — plus a minimal vim editing engine (#667), Esc-interrupt with a defanged Ctrl+C (#625), fully editable multi-line input (#621), slash-command argument hints (#631), a persistent session-stats line (#657), and restored /cost, /skills, and /model (#627, #629, #630). Reliability: the production compaction pipeline is wired and auto-compact actually applies its result (#587, #607), full retry lane + model fallback + message-history caching (#586), parallel Agent fan-out with the concurrency-cap deadlock fixed (#590), killing a background agent really stops the run (#606), and output styles work end-to-end (#640). Codebase stats: 1,170 Python files, 256,909 lines (up from 233,520 lines on 2026-06-11).
• 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). 📚 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:

• ✅ 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).

🌿 /eco Token Compression — -80% Bash-output tokens, measured

Long agentic sessions drown in tool output: failing test logs, git progress spam, 2,000-line listings. Toggle /eco on and ClawCodex compresses the model-bound rendering of every Bash result with deterministic filters ported from RTK's method set — failure-focused test summaries, command-scoped ceremony stripping, log deduplication with [×N] counts, and a recoverable head-cap — while the full raw output stays on disk behind a runnable recovery hint. No model in the loop, no command rewriting, nothing to learn.

$ pytest        # 128 lines → 37 lines, 1,347 → 390 tokens (-71%)
Pytest: 5 failed, 29 passed in 0.04s

1. [FAIL] test_unknown_sku_message
   with pytest.raises(OrderError, match="unknown sku 'gold-bar'"):
   >           o.total()
   tests/test_orders.py:34:
   ⋮
5. [FAIL] test_truncate_one
   >       assert truncate_words("alpha beta", 1) == "alpha..."
   E       AssertionError: assert 'alpha beta...' == 'alpha...'
[full output: ~/.clawcodex/<ws>/<session>/eco/1707_pytest.log]
Command failed with exit code 1

Measured, not estimated. RTK's README models a 30-minute session and estimates -80%. We ran the experiment instead: a 27-operation corpus of real command outputs — failing pytest/go test/jest runs, pip/npm installs, git workflows, repo-scale listings, a 34,000-line system log, captured live (RTK's own "never synthetic" fixture rule) — replayed through the exact production pipeline, counting tiktoken cl100k_base tokens of the model-bound text with /eco off vs on:

The corpus also includes 8 operations that (correctly) pass through byte-identical — a clean git status, docker ps, ruff check findings, a small failing go test, a 370-line grep that sits under the head-cap threshold — because /eco guarantees never worse: a compression that doesn't beat the raw rendering is discarded. Full tables: eval/eco/results/results.md.

RTK rewrites commands into its own CLI (rtk ls, rtk read, rtk grep), so every operation in its session model compresses. /eco deliberately compresses results only — the command the model wrote is the command that runs — and small outputs pass through untouched. Recomputing RTK's session table with our measured ratios (0% where our corpus shows passthrough at RTK's assumed sizes):

Under RTK's averaged assumptions (every cat ≈ 2,000 tokens, every ls ≈ 200) the honest number for a results-only compressor is -19% — those mid-size outputs are exactly what ClawCodex already handles with Read-tool line caps and 30k-char Bash truncation. But real sessions aren't averages: they're fat-tailed, and one 2,000-line git log, one failing suite, or one npm install blows more context than fifty small commands. /eco targets precisely that tail — which is why the measured number on real outputs is -80%, the same figure RTK estimates, with none of the risk of rewriting commands.

The RTK safety rules, kept (see src/eco/):

• Never worse — every compressed rendering is token-checked against the exact baseline it replaces; the baseline wins ties. Worst case is 0% saved, never negative.
• Failures survive — error/failure lines are never rewritten, only ceremony drops; a green summary with a non-zero exit code is treated as untrusted and passed through.
• Everything recoverable — lossy compressions tee the full output to the session dir and append a runnable hint ([see remaining: tail -n +61 …]); no tee, no compression.
• Semantics untouched — exit codes, is_error, images, background tasks, and interrupted runs are never altered; any filter exception falls back to passthrough.

/eco status shows per-filter savings for the session. Compression stacks with the DeepSeek prefix cache: the cache makes the stable prefix nearly free, /eco shrinks the fresh suffix every turn actually pays for. Reproduce:

python3 eval/eco/capture_corpus.py --workdir /tmp/eco-bench   # capture real outputs
.venv/bin/python eval/eco/measure.py                          # replay + count tokens

⭐ 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, MOONSHOT_API_KEY), so most providers work without editing config.json.

Interactive UI (TypeScript Ink TUI)

The interactive UI is the TypeScript Ink TUI — a terminal client that spawns and owns a Python agent-server child and talks to it over a pipe (NDJSON). Running clawcodex with no mode flags launches it; clawcodex tui is the explicit form. (The former in-process Rich REPL and Textual TUI were removed in favor of this single, higher-fidelity client.)

> Hello!
Assistant: Hi! I'm ClawCodex, a Python reimplementation...

> /help                       # Show commands
> /theme dark                 # Switch color theme
> @src/cli.py                 # @-mention a file (fuzzy file index)
> /explain-code qsort.py      # Run a SKILL.md skill (or /skill …)

# Needs Node 18+ and a built ui-tui/dist (the installer builds it); `clawcodex -p` is the no-Node headless path.

Complete CLI

clawcodex                       # Interactive Ink TUI (default)
clawcodex tui                   # Interactive Ink TUI (explicit)
clawcodex login                 # Configure API keys (interactive)
clawcodex logout anthropic      # Remove Claude Pro/Max OAuth credentials
clawcodex logout openai         # Remove ChatGPT subscription OAuth credentials
clawcodex config                # Show ~/.clawcodex/config.json-backed settings
clawcodex --version             # Version string

# Non-interactive / scripting (pipes, CI, agents)
clawcodex -p "Summarize src/cli.py"
clawcodex -p "Hello" --output-format json
clawcodex -p --output-format stream-json --input-format stream-json < events.ndjson

# Overrides for a single run
clawcodex --provider anthropic --model claude-sonnet-4-6 -p "Hi"
clawcodex --max-turns 10 --allowed-tools Read,Grep -p "Find TODOs"

# Permission control (REPL, TUI, and -p all honor these)
clawcodex --permission-mode plan                       # plan / acceptEdits / dontAsk
clawcodex --dangerously-skip-permissions -p "ls"       # bypass all permission checks
clawcodex --allow-dangerously-skip-permissions         # allow /permission-mode bypass later

Claude Pro/Max subscription login

Run clawcodex login, choose anthropic, then choose subscription. The CLI opens Claude's PKCE authorization page; paste the returned authorization code back into the prompt. ClawCodex stores the OAuth tokens in ~/.clawcodex/anthropic-oauth.json with user-only permissions, refreshes them automatically, and uses the subscription whenever no Anthropic API key is set. An explicit ANTHROPIC_API_KEY or configured Anthropic API key takes precedence.

Important: Anthropic does not officially support using Claude Pro/Max subscriptions from third-party clients. This integration may stop working and remains subject to Anthropic's terms. The login flow requires explicit confirmation before opening the authorization page.

Use clawcodex config to check connection status and clawcodex logout anthropic to delete the stored OAuth credentials.

ChatGPT subscription login (OpenAI)

Run clawcodex login, choose openai, then choose subscription. Three login methods are offered: browser (opens ChatGPT's PKCE authorization page and completes via a localhost:1455 redirect — the same flow the Codex CLI uses), device-code (for headless/SSH machines: enter a short code at auth.openai.com/codex/device), and import-codex-cli (shown when a Codex CLI ChatGPT login exists in ~/.codex/auth.json — copies it). Tokens are stored in ~/.clawcodex/openai-oauth.json with user-only permissions and refresh automatically. With a subscription connected and no OpenAI API key set, requests go to the ChatGPT Codex backend (Responses API) and draw on your plan's allowance — the cost display shows $0. An explicit OPENAI_API_KEY or configured OpenAI API key takes precedence. Subscription models: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark.

Important: using a ChatGPT plan from third-party clients rides the Codex CLI's official OAuth app, remains subject to OpenAI's terms, and may stop working. The login flow requires explicit confirmation.

Use clawcodex config to check connection status and clawcodex logout openai to delete the stored OAuth credentials.

--dangerously-skip-permissions disables every tool permission check for the session. Recommended only inside sandboxed containers/VMs with no internet access. The flag is refused when the process is running as root/sudo unless IS_SANDBOX=1 or CLAUDE_CODE_BUBBLEWRAP=1 is set.

📊 Status

Core Systems

Tool System (30+ Tools Implemented)

Roadmap Progress

• ✅ Phase 0: Installable, runnable CLI
• ✅ Phase 1: Core Claude Code MVP experience
• ✅ Phase 2: Real tool calling loop
• 🟡 Phase 3: Context depth, permission integration, /resume-class recovery (in progress)
• 🟡 Phase 4: MCP runtime depth, plugins, extensibility (tools exist; platform work continues)
• ⏳ Phase 5: Python-native differentiators

See FEATURE_LIST.md for detailed feature status and PR guidelines.

🚀 Quick Start

Install

# Install the latest release from PyPI (recommended). The distribution is
# named clawcodex-cli; the installed command remains `clawcodex`.
pipx install clawcodex-cli
# Or: uv tool install clawcodex-cli
# Or, inside an activated virtual environment: pip install clawcodex-cli

# Run the CLI
clawcodex --help

For development from a source checkout:

git clone https://github.com/agentforce314/clawcodex.git
cd clawcodex

# Create venv (uv recommended)
uv venv --python 3.11
source .venv/bin/activate

# Install package + entry point (recommended)
uv pip install -e ".[dev]"

# Alternative: requirements only, then editable install
# uv pip install -r requirements.txt && uv pip install -e .

Configure

Option 1: Interactive (Recommended)

clawcodex login
# or: python -m src.cli login

This flow will:

1. ask you to choose a provider: anthropic / openai / gemini / zai / minimax / openrouter / deepseek, or any OpenAI-compatible vendor (together, novita, fireworks, moonshot, nvidia-nim, siliconflow, deepinfra, huggingface, …) and local servers (ollama / vllm / sglang)
2. ask for that provider's API key
3. optionally save a custom base URL
4. optionally save a default model
5. set the selected provider as default

The configuration file is saved in ~/.clawcodex/config.json. Example structure:

{
  "default_provider": "deepseek",
  "providers": {
    "anthropic": {
      "api_key": "your-api-key",
      "base_url": "https://api.anthropic.com",
      "default_model": "claude-sonnet-4-6"
    },
    "openai": {
      "api_key": "your-api-key",
      "base_url": "https://api.openai.com/v1",
      "default_model": "gpt-5.4"
    },
    "zai": {
      "api_key": "your-api-key",
      "base_url": "https://api.z.ai/api/coding/paas/v4",
      "default_model": "glm-5.2"
    },
    "minimax": {
      "api_key": "your-api-key",
      "base_url": "https://api.minimax.io/anthropic",
      "default_model": "MiniMax-M3"
    },
    "openrouter": {
      "api_key": "your-api-key",
      "base_url": "https://openrouter.ai/api/v1",
      "default_model": "deepseek/deepseek-v4-pro"
    },
    "deepseek": {
      "api_key": "your-api-key",
      "base_url": "https://api.deepseek.com",
      "default_model": "deepseek-v4-pro"
    }
  },
  "session": {
    "auto_save": true,
    "max_history": 100
  },
  "settings": {
    "advisor_enabled": false,
    "advisor_model": "claude-sonnet-4-6",
    "advisor_client_mode": false,
    "advisor_provider": "openai",
    "modelLimits": {
      "private-1m-model": {
        "contextWindow": 1000000,
        "maxOutputTokens": 32768
      }
    }
  },
  "env": {
    "TAVILY_API_KEY": "tvly-YOUR-TAVILY-API-KEY"
  }
}

The built-in Minimax provider passes an SDK base URL to the Anthropic SDK. Use https://api.minimax.io/anthropic globally or https://api.minimaxi.com/anthropic in China; the SDK appends /v1/messages. The final Messages request URLs are https://api.minimax.io/anthropic/v1/messages and https://api.minimaxi.com/anthropic/v1/messages. The OpenAI-compatible API roots are https://api.minimax.io/v1 globally and https://api.minimaxi.com/v1 in China.

• session — REPL session persistence: auto_save writes each session automatically; max_history caps retained turns.
• settings — the advisor (reviewer) feature. advisor_enabled is the master switch — false by default, so the advisor is OFF unless you opt in (set it to true, or run /advisor <provider>:<model> which flips it on). advisor_provider / advisor_model pick the reviewer model; advisor_client_mode routes the call via the client.
• settings.modelLimits — context/output limits for private or gateway models absent from the built-in catalog. Keys may be exact model IDs, model prefixes, or host-qualified IDs such as localhost:4000:private-model; exact matches beat prefixes and host-qualified keys beat bare keys within the same match type. Built-in catalog metadata remains authoritative.
• env — secrets and environment values injected at startup (e.g. TAVILY_API_KEY for web search). Managed via clawcodex config; keys here are exported into the process environment without overriding anything you already set in your shell.

Run

clawcodex                  # Start inline REPL (same as python -m src.cli)
clawcodex --help           # All flags: -p, --provider, --model, …

That's it! Configure keys, then run the CLI or REPL.

💡 Usage

REPL Commands