**English** | [中文](#中文版) | [Français](https://github.com/gpt-agi/clawd-code/blob/HEAD/docs/i18n/README_FR.md) | [Русский](https://github.com/gpt-agi/clawd-code/blob/HEAD/docs/i18n/README_RU.md) | [हिन्दी](https://github.com/gpt-agi/clawd-code/blob/HEAD/docs/i18n/README_HI.md) | [العربية](https://github.com/gpt-agi/clawd-code/blob/HEAD/docs/i18n/README_AR.md) | [Português](https://github.com/gpt-agi/clawd-code/blob/HEAD/docs/i18n/README_PT.md)
# 🚀 Claude Code Python
**A Complete Python Reimplementation Based on Real Claude Code Source**
*From TypeScript Source → Rebuilt in Python with ❤️*
***
[](https://github.com/GPT-AGI/Clawd-Code/stargazers)
[](https://github.com/GPT-AGI/Clawd-Code/network/members)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
**🔥 Active Development • New Features Weekly 🔥**
***
## 🎯 Why Clawd Code?
**Clawd Code** 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
**Token Streaming + Tool-Aware Agent Loop**
**Programmable Skill Runtime with Tool Sandboxing**
**Instant Web Fetch for External Context**
**Real CLI • Real Usage • Real Community**
**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
## ✨ Features
### Streaming Agent Experience
```text
>>> /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
```md
---
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
```python
providers = ["Anthropic Claude", "OpenAI GPT", "Zhipu GLM"] # + easy to extend
```
### Interactive REPL
```text
>>> 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
```bash
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](https://github.com/gpt-agi/clawd-code/blob/HEAD/FEATURE_LIST.md) for detailed feature status and PR guidelines.**
## 🚀 Quick Start
### Install
```bash
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)
```bash
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:
```json
{
"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
```bash
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 ` | 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:
```text
/.clawd/skills//SKILL.md
```
Example:
```md
---
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**
```text
❯ /
❯ /
```
Example:
```text
❯ /explain-code qsort.py
```
**Notes**
- User-level skills: `~/.clawd/skills//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
```text
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!**
```bash
# Quick dev setup
pip install -e .[dev]
python -m pytest tests/ -v
```
See [CONTRIBUTING.md](https://github.com/gpt-agi/clawd-code/blob/HEAD/CONTRIBUTING.md) for guidelines.
***
## 📖 Documentation
- **[SETUP_GUIDE.md](https://github.com/gpt-agi/clawd-code/blob/HEAD/docs/guide/SETUP_GUIDE.md)** — Detailed installation
- **[CONTRIBUTING.md](https://github.com/gpt-agi/clawd-code/blob/HEAD/CONTRIBUTING.md)** — Development guide
- **[TESTING.md](https://github.com/gpt-agi/clawd-code/blob/HEAD/docs/guide/TESTING.md)** — Testing guide
- **[CHANGELOG.md](https://github.com/gpt-agi/clawd-code/blob/HEAD/CHANGELOG.md)** — Version history
***
## ⚡ Performance
- **Startup**: < 1 second
- **Memory**: < 50MB
- **Response**: Turn-based assistant output with Rich markdown rendering
***
## 🔒 Security
✅ **Basic Local Safety Practices**
- No sensitive data in Git
- API keys obfuscated in config
- `.env` files ignored
- Safe for local development workflows
***
## 📄 License
MIT License — See [LICENSE](https://github.com/gpt-agi/clawd-code/tree/HEAD/LICENSE)
***
## 🙏 Acknowledgments
- Based on Claude Code TypeScript source
- Independent educational project
- Not affiliated with Anthropic
***
### 🌟 Show Your Support
If you find this useful, please **star** ⭐ the repo!
**Made with ❤️ by Clawd Code Team**
[⬆ Back to Top](#-clawd-codex)