An AI agent CLI built on the Anthropic Messages API with multi-tool and skill support. Supports interactive REPL and single-prompt modes. The root pyccode.py is a 5-line thin wrapper; all logic lives in the pyccode/ package.

• 7 built-in tools: bash, read, write, edit, TodoWrite, skill, run_subagent
• Skill loading: Auto-discovers skills/*/SKILL.md files and lets the agent load detailed instructions on demand
• Subagent system: Delegate complex subtasks to isolated in-process agents
• Task tracking: Built-in todo list with pending/in_progress/completed states
• Four-layer context management:
  • Per result (>50K chars): written to ~/.pyccode/projects/<sanitized-cwd>/<sessionId>/tool-results/<id>.{txt|json} (never inside the project) and replaced in conversation with a ~2KB head-only summary
  • Per message (>200K chars total): largest results persisted first until under budget
  • Per turn (>10 uncleared compactable results in history): oldest replaced with [Old tool result content cleared], keeping the most recent 5; excludes run_subagent (one-shot outputs)
  • Per turn (previous input_tokens > 150K): history is LLM-summarized into a 9-section compact summary; replaced with [boundary, summary, *last_4_messages] so long sessions continue past the context window
• Transcript logging: every main-agent turn is mirrored to ~/.pyccode/projects/<sanitized-cwd>/<sessionId>.jsonl as append-only JSONL with a parentUuid chain, so past sessions can be inspected with cat / grep / jq. Write-only in MVP — resume is a future task.
• Anthropic-compatible: Works with any provider supporting the Anthropic Messages API

git clone https://github.com/SutraHsing/pyccode.git
cd pyccode
uv sync

Requires Python >=3.12.

# Interactive REPL (type q/quit/exit to stop)
python pyccode.py

# Single task
python pyccode.py "your task here"

Create a .env file:

ANTHROPIC_BASE_URL=https://your-api-endpoint.com/api/anthropic
ANTHROPIC_API_KEY=your-api-key-here
MODEL_NAME=claude-sonnet-4-5-20250929       # optional, defaults to this
ANTHROPIC_TIMEOUT=600                         # optional, seconds (default 600)

Add skills under skills/<skill-name>/SKILL.md. Each skill file must start with YAML frontmatter:

---
name: example-skill
description: Use when the agent needs this specific guidance.
---

# Example Skill

Detailed instructions go here.

When skills are present, pyccode injects their names and descriptions into the first user message. The agent can then call the skill tool to load the full instructions and the skill directory path, which allows reference files beside SKILL.md to be used as needed.

• anthropic>=0.75.0
• dotenv>=0.9.9

• Sutra Hsing