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

• 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).
• 2026-05-29: Remote-bridge parity + CLI transports (#200–#226) — full port of the remote-control bridge across phases 0–18: bridge API client, child-CLI session runner, env-less v2 orchestrator, multi-session daemon, worktree spawn, in-place reconnect, perpetual mode with crash recovery, JWT refresh, and the v1 WebSocketTransport / SerialBatchEventUploader write path with hybrid dispatch. Plus the CLI transport factory, coalescing worker-state uploader, and RemoteIO bridge (#226); new /buddy virtual-companion command — hatch / pet / status / mute (#225).
• 2026-05-21: Codebase stats — Total Python files: 890 files; Total Lines of Python Code: 183,768 lines (up from 177,428 lines on 2026-05-16; net −4 files from the src/tool_system/agent_loop.py consolidation into src/query/query.py).
• 2026-05-21: /advisor token-efficient coding mode (#181–#193) — pair a cheap worker (haiku-4-5, $1/$5 per Mtok) with an expensive reviewer (opus-4-7, $5/$25) consulted only at decision points; ~6× cheaper than opus-only on typical sessions. Explicit <provider>:<model> syntax, cross-provider routing (e.g. deepseek/deepseek-v4-pro worker + claude-opus-4-7 advisor via litellm), and live worker/advisor token + USD cost in the status bar.
• 2026-05-16: Codebase stats — Total Python files: 894 files; Total Lines of Python Code: 177,428 lines (up from 167,034 lines on 2026-05-14; ~+10.4k lines in two days, mostly ESC-cancellation hardening + image-handling parity).
• 2026-05-16: Image-handling parity (Tier C, #149/#154/#155/#156) — Read tool TS image pipeline (sniff, resize/compress, base64 cap); @image.png mentions inline as real ImageBlocks instead of mojibake; cross-provider Anthropic image/document → OpenAI image_url/file translation; pre-API base64 size validation in BaseProvider.

📚 Older items have moved to the full News archive.

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!

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

View star history on star-history.com

>>> /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

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

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 = ["anthropic", "openai", "glm", "minimax", "openrouter", "deepseek"]  # OpenAI-compatible & GLM APIs; more can be added

The default interactive UI is the inline prompt_toolkit + Rich REPL (transcript in scrollback, tool-aware status row). Use clawcodex --tui or the /tui slash command inside the REPL to launch the Textual in-app experience when you want it.

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

>>> /help          # Show commands
>>> /tools         # List registered tools
>>> /tui           # Hand off to the Textual TUI
>>> /stream on     # Live response rendering
>>> /save          # Save session
>>> Tab            # Auto-complete
>>> /explain-code qsort.py   # Run a SKILL.md skill (or /skill …)

# Multi-line input: Shift+Enter, Meta/Alt+Enter, or `\` then Enter for newline; plain Enter submits.

clawcodex                       # Inline REPL (default)
clawcodex --tui                 # Textual TUI
clawcodex --stream              # REPL with live rendering
clawcodex login                 # Configure API keys (interactive)
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

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

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

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 .

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

This flow will:

1. ask you to choose a provider: anthropic / openai / glm / minimax / openrouter / deepseek
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 in ~/.clawcodex/config.json. Example structure:

{
  "default_provider": "anthropic",
  "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"
    },
    "glm": {
      "api_key": "your-api-key",
      "base_url": "https://open.bigmodel.cn/api/paas/v4",
      "default_model": "zai/glm-5"
    },
    "minimax": {
      "api_key": "your-api-key",
      "base_url": "https://api.minimaxi.com/anthropic",
      "default_model": "MiniMax-M2.7"
    },
    "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_model": "claude-sonnet-4-6",
    "advisor_client_mode": false,
    "advisor_provider": "openai"
  },
  "env": {
    "TAVILY_API_KEY": "tvly-YOUR-TAVILY-API-KEY"
  }
}

• session — REPL session persistence: auto_save writes each session automatically; max_history caps retained turns.
• settings — the advisor model used for background helpers (advisor_provider / advisor_model, and advisor_client_mode to route via the client).
• 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.

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

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

Skills are markdown-based slash commands stored under .clawcodex/skills. Each skill lives in its own directory and must be named SKILL.md.

1) Create a project skill

Create:

<project-root>/.clawcodex/skills/<skill-name>/SKILL.md

Example:

---
description: Explains code with diagrams and analogies
when_to_use: Use when explaining how code works
allowed-tools:
  - Read
  - Grep
  - Glob
arguments: [path]
---

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

2) Use it in the REPL

❯ /
❯ /<skill-name> <args>

Example:

❯ /explain-code qsort.py

Notes

• User-level skills: ~/.clawcodex/skills/<skill-name>/SKILL.md
• Tool limits: allowed-tools controls which tools the skill can use.
• Arguments: use $ARGUMENTS, $0, $1, or named args like $path (from arguments).
• Placeholder syntax: use $path, not ${path}.

Every app under demos/ was generated end-to-end by ClawCodex itself — same CLI you just installed, same agent loop, same tools. No hand-edits 🙂

cd demos/crm-app   # or linkedin-app / minecraft-app
npm install
npm run dev        # vite dev server

Want to see how it's done? Open ClawCodex in any empty directory and ask it to build something — these three were generated exactly that way.

• Not a clone — Ported from actual TypeScript implementation
• Architectural fidelity — Maintains proven design patterns
• Improvements — Better error handling, more tests, cleaner code

• Type hints — Full type annotations
• Modern Python — Uses 3.10+ features
• Idiomatic — Clean, Pythonic code

• 3-step setup — Clone, configure (clawcodex login), run (clawcodex)
• Interactive config — Provider, base URL, and default model in one flow
• Inline or TUI — Default terminal-native REPL; opt-in Textual UI
• Scriptable — -p / JSON / NDJSON for automation
• Session persistence — Save and reload conversations

For the six core abstractions (query loop, tools, tasks, two-tier state, memory, hooks) and the golden path from user input to model output, see docs/ARCHITECTURE.md. It is the recommended starting point for new contributors.

The reference for the original Claude Code architecture is at claude-code-from-source/book/ch01-architecture.md; the chapter-by-chapter port gap analyses and refactoring plans live under my-docs/.

clawcodex/
├── src/
│   ├── cli.py              # CLI entry (console: clawcodex)
│   ├── entrypoints/        # Headless (-p) and TUI bootstraps
│   ├── repl/               # Inline REPL (prompt_toolkit + Rich)
│   ├── tui/                # Textual UI (--tui, /tui)
│   ├── providers/          # Anthropic, OpenAI, GLM, Minimax, OpenRouter, DeepSeek
│   ├── agent/              # Conversation, session, prompts
│   ├── tool_system/        # Agent loop, tools, schemas
│   ├── skills/             # SKILL.md loading and skill tool
│   ├── services/           # MCP, compact, IDE bridge, tool execution, …
│   ├── context_system/     # Workspace / git / CLAUDE.md context
│   ├── permissions/        # Permission modes and bash parsing
│   ├── hooks/              # Hook types and execution helpers
│   └── command_system/     # Slash commands and substitution
├── typescript/             # Reference / parity source (not required to run Python CLI)
├── tests/                  # pytest suites
├── docs/                   # Guides, i18n READMEs, refactor notes
├── .clawcodex/skills/      # Project-local skills (optional)
├── FEATURE_LIST.md         # Capability matrix and roadmap
└── pyproject.toml          # Package metadata and clawcodex script

We welcome contributions!

# Quick dev setup
pip install -e .[dev]
python -m pytest tests/ -v

See CONTRIBUTING.md for guidelines.

• SETUP_GUIDE.md — Detailed installation
• CONTRIBUTING.md — Development guide
• TESTING.md — Testing guide
• CHANGELOG.md — Version history

• Startup: < 1 second
• Memory: < 50MB
• Response: Turn-based assistant output with Rich markdown rendering

✅ Basic Local Safety Practices

• No sensitive data in Git
• API keys obfuscated in config
• .env files ignored
• Safe for local development workflows

MIT License — See LICENSE

• Based on Claude Code TypeScript source
• Independent educational project
• Not affiliated with Anthropic