Real CLI • Real Usage • Real Community

• ✅ Working CLI — Not just code, but a fully functional command-line tool you can use today
• ✅ Based on Real Source — Ported from actual Claude Code TypeScript implementation
• ✅ Maximum Fidelity — Preserves original architecture while optimizing
• ✅ Python Native — Clean, idiomatic Python with full type hints
• ✅ User Friendly — Easy setup, interactive REPL, comprehensive docs
• ✅ Continuously Improved — Enhanced error handling, testing, documentation

🚀 Try it now! Fork it, modify it, make it yours! Pull requests welcome!

⭐ Star History

✨ Features

Flexible Skill Systems

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

providers = ["Anthropic Claude", "OpenAI GPT", "Zhipu GLM"]  # + easy to extend

Interactive REPL

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

>>> /help         # Show commands
>>> /             # Show all commands & skills
>>> /save         # Save session
>>> /multiline    # Multi-paragraph input
>>> Tab           # Auto-complete
>>> /explain-code qsort.py   # Run a skill

Complete CLI

clawd              # Start REPL
clawd login        # Configure API
clawd --version    # Check version
clawd config       # View settings

📊 Status

| Component | Status | Count | | ------------- | ---------- | --------- | | REPL Commands | ✅ Complete | 6+ built-ins | | Tool System | ✅ Complete | 30+ tools | | Automated Tests | ✅ Present | Core suites for skills, providers, REPL, tools, context | | Documentation | ✅ Complete | 10+ docs |

Core Systems

| System | Status | Description | |--------|--------|-------------| | CLI Entry | ✅ | clawd, login, config, --version | | Interactive REPL | ✅ | Rich interactive output, history, tab completion, multiline | | Multi-Provider | ✅ | Anthropic, OpenAI, GLM support | | Session Persistence | ✅ | Save/load sessions locally | | Agent Loop | ✅ | Tool calling loop implementation | | Skill System | ✅ | SKILL.md-based slash-command skills with args + tool limits | | Context Building | 🟡 | Initial prompt injection for workspace, git, and CLAUDE.md; deeper project understanding still needed | | Permission System | 🟡 | Framework exists, needs integration |

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 | ✅ Complete | | 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, permissions, recovery (in progress)
• ⏳ Phase 4: MCP, plugins, extensibility
• ⏳ Phase 5: Python-native differentiators

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

🚀 Quick Start

Install

git clone https://github.com/GPT-AGI/Clawd-Code.git
cd Clawd-Code

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

# Install
uv pip install -r requirements.txt

Configure

Option 1: Interactive (Recommended)

python -m src.cli login

This flow will:

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

{
  "default_provider": "glm",
  "providers": {
    "anthropic": {
      "api_key": "base64-encoded-key",
      "base_url": "https://api.anthropic.com",
      "default_model": "claude-sonnet-4-20250514"
    },
    "openai": {
      "api_key": "base64-encoded-key",
      "base_url": "https://api.openai.com/v1",
      "default_model": "gpt-4"
    },
    "glm": {
      "api_key": "base64-encoded-key",
      "base_url": "https://open.bigmodel.cn/api/paas/v4",
      "default_model": "glm-4.5"
    }
  }
}

Run

python -m src.cli          # Start REPL
python -m src.cli --help   # Show help

That's it! Start chatting with AI in 3 steps.

💡 Usage

REPL Commands

| Command | Description | | ------------ | --------------------- | | / | Show commands & skills | | /help | Show all commands | | /save | Save session | | /load <id> | Load session | | /multiline | Toggle multiline mode | | /clear | Clear history | | /exit | Exit REPL |

Skills (Slash Commands)

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

1) Create a project skill

Create:

<project-root>/.clawd/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: ~/.clawd/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}.

🎓 Why Clawd Codex?

Based on Real Source Code

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

Python Native

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

User Focused

• 3-step setup — Clone, configure, run
• Interactive config — clawd login guides you
• Rich REPL — Tab completion, syntax highlighting
• Session persistence — Never lose your work

📦 Project Structure

Clawd-Code/
├── src/
│   ├── cli.py           # CLI entry
│   ├── providers/       # LLM providers
│   ├── repl/            # Interactive REPL
│   ├── skills/          # SKILL.md loading and creation
│   └── tool_system/     # Tool registry, loop, validation
├── tests/               # Core test suite
├── .clawd/
│   └── skills/          # Project-local custom skills
└── FEATURE_LIST.md      # Current feature status

🤝 Contributing

We welcome contributions!

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

See CONTRIBUTING.md for guidelines.

📖 Documentation

• SETUP_GUIDE.md — Detailed installation
• **[CONTRIBU