My personal pi configuration — agents, skills, extensions, and prompts that shape how pi works for me.
Clone this repo directly to ~/.pi/agent/ — pi auto-discovers everything from there (extensions, skills, agents, AGENTS.md, mcp.json). No symlinks, no manual wiring.
# 1. Install pi (https://github.com/badlogic/pi)
# 2. Clone this repo as your agent config
mkdir -p ~/.pi
git clone git@github.com:karan-zipline/dotpi ~/.pi/agent
# 3. Run setup (installs packages + extension deps)
cd ~/.pi/agent && ./setup.sh
# 4. Add your API keys to ~/.pi/agent/auth.json
# 5. Restart picd ~/.pi/agent && git pullThis config uses native pi subagents via the upstream @tintinweb/pi-subagents package. Each subagent is a programmatic pi AgentSession with its own identity, tools, skills, model, and thinking level — no cmux/tmux pane is required.
- Subagents — in-process pi sessions launched with the
Agenttool; background agents return IDs and report results back to the parent. - Agent definitions (
agents/*.md) — one source of truth for model, tools, skills, max turns, prompt mode, and identity per role. - Workflow skills — Superpowers-inspired gates for brainstorming, planning, implementation, debugging, review, and completion.
- Subagent-driven development — fresh worker per task, followed by spec compliance review and code quality review.
- Agent control tools — use
get_subagent_resultfor background results andsteer_subagentto redirect running agents. - Papercuts — log small workflow frictions immediately with
log_papercut; run/papercut_reviewonly on explicit request.
feature/change request
-> brainstorming
-> approved design spec in docs/pi/specs/
-> writing-plans with one integrated review
-> implementation plan with durable progress ledger in docs/pi/plans/
-> subagent-driven-development
-> worker per task
-> spec-reviewer
-> code-quality-reviewer
-> final reviewer
-> finishing-a-development-branch
For bugs and failures:
systematic-debugging -> debugger -> failing test/reproduction -> worker fix -> review -> verification-before-completion
Specialized roles with baked-in identity, workflow, and review rubrics. Local definitions in agents/ are loaded by @tintinweb/pi-subagents and override its defaults.
| Agent | Source | Model | Thinking | Purpose |
|---|---|---|---|---|
| general-purpose | upstream override | GPT-5.6 Terra | high | Complex research and multi-step work |
| planner | local | GPT-5.6 Sol | medium | Brainstorms and writes durable specs/plans; never implements |
| scout | local | GPT-5.6 Luna | high | Fast codebase reconnaissance without edits |
| worker | local | GPT-5.6 Luna | high | Implements one scoped task, verifies it, and commits when requested |
| spec-reviewer | local | GPT-5.6 Sol | low | Checks implementation matches the task/spec exactly |
| code-quality-reviewer | local | GPT-5.6 Sol | low | Reviews maintainability, tests, security, performance, simplicity |
| reviewer | local | GPT-5.6 Sol | medium | Final whole-branch/general review |
| debugger | local | GPT-5.6 Terra | high | Systematic root-cause investigation for failures |
| researcher | local | GPT-5.6 Terra | high | Deep technical research without implementation |
| papercut-reviewer | local | GPT-5.6 Luna | high | User-triggered review of session workflow friction |
Loaded on-demand when the context matches.
| Skill | When to Load |
|---|---|
| brainstorming | Creative/feature/behavior work before implementation |
| product-brainstorming | Product-level idea generation, opportunity exploration, and feature concept sparring |
| roadmap-update | Creating, updating, reprioritizing, or communicating product roadmaps |
| writing-plans | Approved spec or multi-step requirements, including one integrated review |
| subagent-driven-development | Executing plans with fresh workers and two-stage per-task review |
| systematic-debugging | Bugs, test failures, build failures, flakes |
| test-driven-development | Behavior changes and bug fixes before production code |
| code-review | Holistic structural audit preloaded by the final whole-branch reviewer |
| receiving-code-review | Before implementing review feedback |
| verification-before-completion | Before claiming done/fixed/passing |
| finishing-a-development-branch | Verify, commit remaining implementation changes, and push the current feature branch |
| dispatching-parallel-agents | Independent scouting/research/debugging domains |
| commit | Making git commits (mandatory for every commit) |
| code-simplifier | Simplifying or cleaning up code |
| github | Working with GitHub via gh CLI |
| session-reader | Reading and analyzing pi session JSONL files |
| service-metrics | Designing, implementing, and auditing production service metrics |
| self-improve | End-of-session retrospective — surfaces improvements and creates todos |
| Extension | What it provides |
|---|---|
| answer/ | /answer command + Ctrl+. — extracts questions into interactive Q&A UI |
| auto-session-name/ | AI-generated session names and /rename-session command |
| @tintinweb/pi-subagents | Upstream package providing Agent, get_subagent_result, steer_subagent, and /agents |
| execute-command/ | execute_command tool — lets the agent self-invoke slash commands |
| log-papercut/ | log_papercut tool — appends small workflow frictions to PAPERCUTS.md |
| todos/ | /todos command + todo tool — file-based todo management |
| Command | Description |
|---|---|
/agents |
Manage native subagent types, inspect running agents, and adjust subagent settings |
/answer |
Extract questions into interactive Q&A |
/papercut_review |
Review the current session for concrete workflow papercuts and log them |
/todos |
Visual todo manager |
Installed via pi install, managed in settings.json.
| Package | Description |
|---|---|
| @tintinweb/pi-subagents | Native subagent sessions, background execution, steering, and custom agent roles |
| chrome-cdp-skill | Chrome DevTools Protocol CLI for visual testing |
| pi-notify | Native terminal notifications when pi finishes a turn |
Extensions from mitsuhiko/agent-stuff: answer, todos
Skills from mitsuhiko/agent-stuff: commit, github
Skills from getsentry/skills: code-simplifier