🚀 Claude Code Python

🚀 Claude Code Python

A Complete Python Reimplementation Based on Real Claude Code Source

From TypeScript Source → Rebuilt in Python with ❤️

🔥 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

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

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:

ask you to choose a provider: anthropic / openai / glm
ask for that provider's API key
optionally save a custom base URL
optionally save a default model
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
CONTRIBUTING.md — Development guide
TESTING.md — Testing guide
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

🙏 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

中文版

🚀 Claude Code Python

基于真实 Claude Code 源码的完整 Python 重实现

从 TypeScript 源码 → 用 Python 重建 ❤️

🔥 活跃开发中 • 每周更新新功能 🔥

FLEXIBLE SKILL SYSTEMS

基于 Markdown 的斜杠技能系统，支持参数替换、工具限制，以及项目级 / 用户级技能加载。

🎯 为什么是 Clawd Code？

Clawd Code 是一个面向真实使用的 Claude Code Python 重构版：它基于真实 TypeScript 架构移植而来，并且交付的是一个可运行的 CLI Agent，而不只是源码镜像。

真实 Agent Runtime — 具备工具调用循环、流式 REPL、会话历史与多轮执行能力
高保真移植 — 尽可能保留 Claude Code 的原始架构，同时做符合 Python 风格的实现
适合继续开发 — 代码可读、测试完善，并支持基于 Markdown 的技能扩展

Token Streaming + Tool-Aware Agent Loop

可编程 Skill Runtime 与工具沙箱

Instant Web Fetch for External Context

真实的 CLI • 真实的使用 • 真实的社区

这是一个真正可跑的 Claude Code 风格 Python 终端工作流：能流式回答、调工具、抓外部上下文，并通过 skills 扩展行为。

🚀 立即试用！Fork 它、修改它、让它成为你的！欢迎提交 Pull Request！

⭐ Star 历史

✨ 特性

Streaming Agent Experience

>>> /stream on
>>> 解释 tests/test_agent_loop.py
[流式回答中...]
• Read (tests/test_agent_loop.py) running...
  ↳ lines 1-180
>>> /render-last

直接回答支持真实 API 流式输出，带工具的 agent loop 也具备更完整的流式体验
内置 /stream 开关用于实时输出，/render-last 可按需把上一条回答重新渲染为 Markdown
专门为终端演示优化：一边看回答流出，一边看到工具调用，并保留稳定回退路径

可编程 Skill Runtime

---
description: 用类比 + 图示解释代码
allowed-tools:
  - Read
  - Grep
  - Glob
arguments: [path]
---

请解释 $path 的实现：先给一个类比，再画一个结构示意图。

基于 SKILL.md 的 Markdown 斜杠命令
支持项目级技能、用户级技能、命名参数替换与工具限制

多提供商支持

providers = ["Anthropic Claude", "OpenAI GPT", "Zhipu GLM"]  # + 易于扩展

交互式 REPL

>>> 你好！
Assistant: 嗨！我是 Clawd Codex，一个 Python 重实现...

>>> /help         # 显示命令
>>> /             # 显示命令与技能
>>> /save         # 保存会话
>>> /multiline    # 多行输入模式
>>> Tab           # 自动补全
>>> /explain-code qsort.py   # 运行一个技能

完整的 CLI

clawd              # 启动 REPL
clawd login        # 配置 API
clawd --version    # 检查版本
clawd config       # 查看设置

📊 状态

组件	状态	数量
REPL 命令	✅ 完成	6+ 内置命令
工具系统	✅ 完成	30+ 工具
自动化测试	✅ 已覆盖	Skills、providers、REPL、tools、context
文档	✅ 完成	10+ 文档

核心系统

系统	状态	描述
CLI 入口	✅	`clawd`、`login`、`config`、`--version`
交互式 REPL	✅	丰富的交互输出、历史记录、Tab 补全、多行输入
多提供商支持	✅	支持 Anthropic、OpenAI、GLM
会话持久化	✅	本地保存/加载会话
Agent Loop	✅	工具调用循环实现
Skill 系统	✅	基于 SKILL.md 的 /skill 技能：参数替换 + 工具限制
上下文构建	🟡	已接入 workspace、git、CLAUDE.md 的基础上下文注入，仍需补强项目级理解
权限系统	🟡	框架已存在，需要集成

工具系统（已实现 30+ 工具）

类别	工具	状态
文件操作	Read, Write, Edit, Glob, Grep	✅ 完成
系统	Bash 执行	✅ 完成
网络	WebFetch, WebSearch	✅ 完成
交互	AskUserQuestion, SendMessage	✅ 完成
任务管理	TodoWrite, TaskManager, TaskStop	✅ 完成
Agent 工具	Agent, Brief, Team	✅ 完成
配置	Config, PlanMode, Cron	✅ 完成
MCP	MCP 工具和资源	✅ 完成
其他	LSP, Worktree, Skill（SKILL.md）, ToolSearch	✅ 完成

路线图进度

✅ 阶段 0：可安装、可运行的 CLI
✅ 阶段 1：Claude Code 核心 MVP 体验
✅ 阶段 2：真实工具调用闭环
🟡 阶段 3：上下文、权限、恢复能力（进行中）
⏳ 阶段 4：MCP、插件、扩展性
⏳ 阶段 5：Python 原生差异化特性

详细功能状态和 PR 指南请查看 FEATURE_LIST.md。

🚀 快速开始

安装

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

# 创建虚拟环境（推荐使用 uv）
uv venv --python 3.11
source .venv/bin/activate

# 安装
uv pip install -r requirements.txt

配置

方式 1：交互式（推荐）

python -m src.cli login

这个流程会：

让你选择 provider：anthropic / openai / glm
让你输入该 provider 的 API key
可选：保存自定义 base URL
可选：保存默认 model
将该 provider 设为默认

配置文件会保存在 ~/.clawd/config.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"
    }
  }
}

运行

python -m src.cli          # 启动 REPL
python -m src.cli --help   # 显示帮助

就这样！ 3 步开始与 AI 对话。

💡 使用

REPL 命令

命令	描述
`/`	显示命令与技能
`/help`	显示所有命令
`/save`	保存会话
`/load <id>`	加载会话
`/multiline`	切换多行模式
`/clear`	清空历史
`/exit`	退出 REPL

Skills（技能 / 斜杠命令）教程

技能是存放在 .clawd/skills 下的 Markdown 斜杠命令。每个技能对应一个目录，并且文件名固定为 SKILL.md。

1）创建项目技能

创建：

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

示例：

---
description: 用类比 + 图示解释代码
when_to_use: 当用户问“这段代码怎么工作？”时使用
allowed-tools:
  - Read
  - Grep
  - Glob
arguments: [path]
---

请解释 $path 的实现：先给一个类比，再画一个结构示意图。

2）在 REPL 中使用

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

示例：

❯ /explain-code qsort.py

补充说明

用户级技能：~/.clawd/skills/<skill-name>/SKILL.md
工具限制：allowed-tools 用于限制技能允许调用的工具集合
参数替换：支持 $ARGUMENTS、$0、$1、以及命名参数（例如 $path，来自 arguments）
占位符写法：请使用 $path，不要写成 ${path}

🎓 为什么选择 Clawd Codex？

基于真实源码

不是克隆 — 从真实的 TypeScript 实现移植而来
架构保真 — 保持经过验证的设计模式
持续改进 — 更好的错误处理、更多测试、更清晰的代码

原生 Python

类型提示 — 完整的类型注解
现代 Python — 使用 3.10+ 特性
符合习惯 — 干净的 Python 风格代码

以用户为中心

3 步设置 — 克隆、配置、运行
交互式配置 — clawd login 引导你完成设置
丰富的 REPL — Tab 补全、语法高亮
会话持久化 — 永不丢失你的工作

📦 项目结构

Clawd-Code/
├── src/
│   ├── cli.py           # CLI 入口
│   ├── providers/       # LLM 提供商
│   ├── repl/            # 交互式 REPL
│   ├── skills/          # SKILL.md 加载与创建
│   └── tool_system/     # 工具注册、循环与校验
├── tests/               # 核心测试套件
├── .clawd/
│   └── skills/          # 项目级自定义技能
└── FEATURE_LIST.md      # 当前功能状态

🤝 贡献

我们欢迎贡献！

# 快速开发设置
pip install -e .[dev]
python -m pytest tests/ -v

查看 CONTRIBUTING.md 了解指南。

📖 文档

SETUP_GUIDE.md — 详细安装说明
CONTRIBUTING.md — 开发指南
TESTING.md — 测试指南
CHANGELOG.md — 版本历史

⚡ 性能

启动时间：< 1 秒
内存占用：< 50MB
响应：回合式输出，支持 Rich Markdown 渲染

🔒 安全

✅ 基础本地安全实践

Git 中无敏感数据
API 密钥在配置中做了基础混淆
.env 文件被忽略
适合本地开发工作流

📄 许可证

MIT 许可证 — 查看 LICENSE

🙏 致谢

基于 Claude Code TypeScript 源码
独立的教育项目
未隶属于 Anthropic

🌟 支持我们

如果你觉得这个项目有用，请给个 star ⭐！

用 ❤️ 制作 by Clawd Code 团队

⬆ 回到顶部

Name		Name	Last commit message	Last commit date
Latest commit History 72 Commits
.clawd/skills		.clawd/skills
.github		.github
assets		assets
docs		docs
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE_example.md		CLAUDE_example.md
CONTRIBUTING.md		CONTRIBUTING.md
FEATURE_LIST.md		FEATURE_LIST.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

🚀 Claude Code Python

🎯 Why Clawd Code?

⭐ Star History

✨ Features

Streaming Agent Experience

Programmable Skill Runtime

Multi-Provider Support

Interactive REPL

Complete CLI

📊 Status

Core Systems

Tool System (30+ Tools Implemented)

Roadmap Progress

🚀 Quick Start

Install

Configure

Option 1: Interactive (Recommended)

Run

💡 Usage

REPL Commands

Skills (Slash Commands)

🎓 Why Clawd Codex?

Based on Real Source Code

Python Native

User Focused

📦 Project Structure

🤝 Contributing

📖 Documentation

⚡ Performance

🔒 Security

📄 License

🙏 Acknowledgments

🌟 Show Your Support

中文版

🚀 Claude Code Python

FLEXIBLE SKILL SYSTEMS

🎯 为什么是 Clawd Code？

⭐ Star 历史

✨ 特性

Streaming Agent Experience

可编程 Skill Runtime

多提供商支持

交互式 REPL

完整的 CLI

📊 状态

核心系统

工具系统（已实现 30+ 工具）

路线图进度

🚀 快速开始

安装

配置

方式 1：交互式（推荐）

运行

💡 使用

REPL 命令

Skills（技能 / 斜杠命令）教程

🎓 为什么选择 Clawd Codex？

基于真实源码

原生 Python

以用户为中心

📦 项目结构

🤝 贡献

📖 文档

⚡ 性能

🔒 安全

📄 许可证

🙏 致谢

🌟 支持我们

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Packages