ApeCode 🦧

Features

Installation

uv sync

Usage

API keys

export OPENAI_API_KEY=your_key # for provider=openai (default)
export ANTHROPIC_API_KEY=your_key # for provider=anthropic
export KIMI_API_KEY=your_key # for provider=kimi

Interactive REPL

uv run ape

One-shot mode

uv run ape "read README.md and summarize project structure"

CLI flags

uv run ape --provider openai --model gpt-4.1-mini # default
uv run ape --provider anthropic --model claude-sonnet-4-20250514
uv run ape --provider kimi --model kimi-k2.5
uv run ape --max-steps 30 --timeout 180
uv run ape --cwd /path/to/repo
uv run ape --sandbox-mode read-only --approval-policy never
uv run ape --plugin-dir ./plugins
uv run ape --mcp-config ./.mcp.json
uv run ape --skill-dir ./custom-skills
uv run ape --yolo "apply a simple refactor in src/"
uv run ape --version

Slash commands (inside REPL)

/help — list all commands
/tools — list registered tools
/skills — list discovered skills
/skill concise-review review src/apecode/cli.py — run a skill with extra request
/plan — show the current task plan
/subagents — list subagent profiles
/delegate reviewer:: review src/apecode/cli.py — delegate to a subagent
/exit — quit

Architecture

user input
 │
 ▼
┌──────────────────────────────────────────────┐
│ cli.py — Typer app, _build_runtime, REPL │
│ ┌────────────────────────────────────────┐ │
│ │ NanoCodeAgent (agent.py) │ │
│ │ ┌──────────┐ ┌──────────────────┐ │ │
│ │ │ ChatModel │◄──│ model_adapters.py │ │ │
│ │ │ protocol │ │ OpenAI/Anthropic/ │ │ │
│ │ │ │ │ Kimi adapters │ │ │
│ │ └──────────┘ └──────────────────┘ │ │
│ │ ┌──────────────────────────────────┐ │ │
│ │ │ ToolRegistry (tools.py) │ │ │
│ │ │ 7 built-in + plugin + MCP tools │ │ │
│ │ │ ToolContext: sandbox + approval │ │ │
│ │ └──────────────────────────────────┘ │ │
│ └────────────────────────────────────────┘ │
│ commands.py — slash command registry │
│ plugins.py — apecode_plugin.json loader │
│ mcp.py — fastmcp stdio bridge │
│ skills.py — SKILL.md discovery + catalog │
│ subagents.py — isolated read-only delegates │
│ system_prompt.py — prompt builder + AGENTS.md│
│ console.py — Rich + prompt-toolkit I/O │
└──────────────────────────────────────────────┘

Module breakdown

Environment Variables

Plugin System

{
 "name": "EchoPlugin",
 "tools": [
 {
 "name": "echo_text",
 "description": "Echo text from JSON args",
 "parameters": {
 "type": "object",
 "properties": { "text": { "type": "string" } },
 "required": ["text"],
 "additionalProperties": false
 },
 "argv": ["python3", "/absolute/path/to/tool.py"],
 "mutating": false,
 "timeout_sec": 60
 }
 ],
 "commands": [
 {
 "name": "quick-review",
 "description": "Run plugin prompt template",
 "usage": "/quick-review <task>",
 "output": "Running quick review...",
 "agent_input_template": "Review this task:\\n{args}"
 }
 ],
 "skills": [
 {
 "name": "plugin-skill",
 "description": "A plugin-provided skill",
 "content": "# Plugin Skill\\n\\nKeep output concise."
 }
 ]
}

MCP Config

{
 "mcpServers": {
 "demo": {
 "command": "python3",
 "args": ["/absolute/path/to/mcp_server.py"],
 "timeout_sec": 30
 }
 }
}

Skills

# concise-review
Review code and answer with concise bullet points.

/skill concise-review review src/apecode/agent.py

Development

# Install dev dependencies
uv sync
# Run tests
uv run pytest
# Run a single test file
uv run pytest tests/test_tools.py -v
# Lint
uv run ruff check src/ tests/
# Lint with auto-fix
uv run ruff check --fix src/ tests/
# Format
uv run ruff format src/ tests/

Project Structure

src/apecode/
├── __init__.py # package version
├── __main__.py # python -m apecode entry
├── cli.py # Typer CLI app + runtime assembly
├── agent.py # NanoCodeAgent core loop
├── tools.py # tool registry + built-in tools
├── model_adapters.py # model adapters (OpenAI/Anthropic/Kimi)
├── commands.py # slash command framework
├── plugins.py # plugin manifest loader
├── mcp.py # MCP stdio bridge
├── skills.py # skill discovery + catalog
├── subagents.py # subagent delegation
├── system_prompt.py # system prompt builder
└── console.py # Rich + prompt-toolkit I/O
tests/
├── test_agent.py
├── test_commands.py
├── test_mcp.py
├── test_model_adapters.py
├── test_plugins.py
├── test_skills.py
├── test_subagents.py
└── test_tools.py

🦧 More from the Author

License