Three-Stage Workflow
1
Research
- Spawns codebase-locator, analyzer agents
- Autonomous question answering via AITL
- Early exit if no implementation needed
Output:
thoughts/shared/research/*.md
2
Design
- Creates implementation plan from research
- Reviews and iterates on plan
- Structured, actionable specifications
Output:
thoughts/shared/plans/*.md
3
Execute
- Implements plan with full SDK tooling
- Commits changes automatically
Output: Modified files, git commit
Features
DSPy ReAct Orchestration
Automatic tool selection and multi-step reasoning powered by DSPy's ReAct implementation.
Claude Agent SDK
Full tooling support — files, shell commands, web search, task management, and more.
Agent-in-the-Loop (AITL)
Autonomous question answering via codebase-aware agent. No human intervention required.
Safety Hooks
Blocks dangerous commands and runs linters automatically on file changes.
Sub-Agent System
Parallel specialized agents for fast codebase exploration and analysis.
Sub-Agents
Specialized agents spawned in parallel for codebase exploration
| Agent | Purpose |
|---|---|
codebase-locator |
Finds WHERE code lives (file paths) |
codebase-analyzer |
Analyzes HOW code works (implementation details) |
codebase-pattern-finder |
Finds similar patterns and usage examples |
thoughts-analyzer |
Extracts insights from research documents |
thoughts-locator |
Discovers relevant documents in thoughts/ |
web-search-researcher |
External web research |
codebase-simplifier |
Simplifies and refines code for clarity |
Slash Commands
Direct workflow stage invocation
| Command | Purpose |
|---|---|
/1_research_codebase |
Research codebase patterns and architecture |
/2_create_plan |
Create implementation plan from research |
/3_review_plan |
Review plan for completeness |
/4_implement_plan |
Execute implementation from plan |
/5_commit |
Create git commit with changes |
/write-claude-md |
Create or update CLAUDE.md |
Installation
git clone https://github.com/0xjgv/pi π
cd π
make link# Ensure ~/.local/bin is in your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcRequires Python 3.13+, uv, and Claude Code
Development
Environment Variables
CLIPROXY_API_BASE |
DSPy LM endpoint |
CLIPROXY_API_KEY |
API key (required) |
PI_LM_DEBUG |
Verbose LM logging (optional) |
Commands
make install # Install dependencies
make check # Run all checks
make test # Run tests
make test-cov # Tests + coverage
make clean # Remove caches