Claude Code Python

A lightweight Claude Code style agent runtime built in Python.

This project focuses on the runtime side of a coding agent rather than UI parity. It provides a compact but functional implementation of:

• multi-step agent loops,
• tool calling,
• sub-agent delegation through task,
• parallel execution,
• and an extensible Python tool architecture.

For Chinese documentation, see README_zh.md.

Project showcase page: https://sansanyuchen.github.io/claude-code-python/

Author:

• Yuchen Wang
• Wangyuchen
• wangyuc@mail.ustc.edu.cn

• Multi-step agent loop with tool calling
• Parallel execution for multiple tool calls
• task tool for spawning one or more sub-agents
• OpenAI-compatible model integration through OPENAI_BASE_URL
• CLI for one-shot runs and interactive chat
• Claude Code style default tools for files, search, shell, and todos
• Workspace-scoped file safety for agent tools

• runtime.py manages the agent loop, model responses, tool dispatch, and tool-result feedback

• model.py wraps an OpenAI-compatible chat completion backend

• tools/base.py defines the tool abstraction and registry
• tools/task.py implements sub-agent delegation, timeout control, and bounded recursion
• tools/filesystem.py provides workspace-safe file operations
• tools/bash.py provides shell command execution

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Set environment variables:

export OPENAI_API_KEY='your_key'
export OPENAI_BASE_URL='https://your-openai-compatible-endpoint/v1'
export CCPY_MODEL='your-model-name'

Examples:

• OpenAI: set OPENAI_API_KEY
• Moonshot / Kimi: set OPENAI_API_KEY, OPENAI_BASE_URL, and CCPY_MODEL

Run one-shot:

ccpy run "Inspect this repo and summarize the Python entry points."

Run interactive chat:

ccpy chat

You can also use the module form:

.venv/bin/python -m claude_code_python.cli run "Inspect this repo and summarize the Python entry points." --workdir .

The main example is a live sub-agent demo driven by a real model.

It asks the root agent to:

• call the built-in task tool,
• launch two sub-agents,
• inspect two separate files,
• and merge the results into one short operational brief.

• run_subagent_demo_live.py
• subagent_demo_live_prompt.txt
• subagent_demo_live_prompt_zh.txt
• task_demo_prompt.txt
• task_demo_prompt_zh.txt

cd /Users/sansan/Desktop/Claude_code_space/claude_python
source ~/.ccpy_env
PYTHONPATH=src .venv/bin/python examples/run_subagent_demo_live.py

• bash
• task
• read_file
• write_file
• edit_file
• multi_edit
• ls
• glob
• grep
• pwd
• mkdir
• todo_read
• todo_write

claude_python/
├── README.md
├── README_zh.md
├── examples/
│   ├── run_subagent_demo_live.py
│   ├── subagent_demo_live_prompt.txt
│   ├── subagent_demo_live_prompt_zh.txt
│   ├── subagent_demo_workspace/
│   ├── task_demo_prompt.txt
│   └── task_demo_prompt_zh.txt
├── pyproject.toml
└── src/
    └── claude_code_python/
        ├── cli.py
        ├── config.py
        ├── model.py
        ├── runtime.py
        └── tools/

• This project focuses on runtime capability rather than UI recreation
• Model quality and latency depend on the configured provider
• The included demo is intentionally small and easy to inspect
• TerminalBench-style evaluation is not bundled yet