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 🔥

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

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

Interactive REPL (default) and Textual TUI (opt-in)

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.

Complete CLI

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.

📊 Status

| Component | Status | Count | | ------------- | ---------- | --------- | | REPL Commands | ✅ Complete | Built-ins + /tools, /stream, /context, /compact, skills, etc. | | Tool System | ✅ Complete | 30+ tools | | Automated Tests | ✅ Present | Tools, agent loop, providers, parity, REPL, auth, and more | | Documentation | ✅ Complete | Guides, i18n READMEs, FEATURE_LIST.md |

Core Systems

| System | Status | Description | |--------|--------|-------------| | CLI Entry | ✅ | clawcodex, login, config, -p / --print, --tui, --stream, --version | | Interactive REPL | ✅ | Default inline REPL; optional Textual TUI; history, tab completion, multiline | | Multi-Provider | ✅ | Anthropic, OpenAI, Zhipu GLM, Minimax, OpenRouter, DeepSeek | | Session Persistence | ✅ | Save/load sessions locally | | Agent Loop | ✅ | Tool calling loop with streaming and headless mode | | Skill System | ✅ | SKILL.md-based slash-command skills with args + tool limits | | Context Building | 🟡 | Workspace / git / CLAUDE.md injection; richer summaries and memory still evolving | | Permission System | 🟡 | Framework and checks; full integration still in progress | | MCP | 🟡 | MCP-oriented tools and wiring; full protocol/runtime polish ongoing |

Tool System (30+ Tools Implemented)

| Category | Tools | Status | |----------|-------|--------| | File Operations | Read, Write, Edit, Glob, Grep | ✅ Complete | | System | Bash execution | ✅ Complete | | Web | WebFetch, WebSearch | ✅ Complete | | Interaction | AskUserQuestion, SendMessage | ✅ Complete | | Task Management | TodoWrite, TaskManager, TaskStop | ✅ Complete | | Agent Tools | Agent, Brief, Team | ✅ Complete | | Configuration | Config, PlanMode, Cron | ✅ Complete | | MCP | MCP tools and resources | 🟡 Tools wired; full client/runtime still evolving | | Others | LSP, Worktree, Skill, ToolSearch | ✅ Complete |

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

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 / 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": "base64-encoded-key",
      "base_url": "https://api.anthropic.com",
      "default_model": "claude-sonnet-4-6"
    },
    "openai": {
      "api_key": "base64-encoded-key",
      "base_url": "https://api.openai.com/v1",
      "default_model": "gpt-5.4"
    },
    "glm": {
      "api_key": "base64-encoded-key",
      "base_url": "https://open.bigmodel.cn/api/paas/v4",
      "default_model": "zai/glm-5"
    },
    "minimax": {
      "api_key": "base64-encoded-key",
      "base_url": "https://api.minimaxi.com/anthropic",
      "default_model": "MiniMax-M2.7"
    },
    "openrouter": {
      "api_key": "base64-encoded-key",
      "base_url": "https://openrouter.ai/api/v1",
      "default_model": "de