Turn pi-coding-agent from a single coding agent into a collaborative ant-colony execution system.
This repository is being re-centered from a general pi setup bundle into a colony-first plugin for complex coding tasks.
Ant Colony for Pi is the primary public product name.
oh-pi remains the current distribution/bootstrap package name during transition, while ant-colony is the primary capability and long-term product direction.
npx oh-pi
# or, once the canonical package is published:
npx pi-agent-colonyThis project is not a fork of and not affiliated with the other project also named oh-pi.
For this repository:
- Ant Colony for Pi = canonical product name
oh-pi= current bootstrap / package / transition name
A formal rename path is being prepared to reduce user confusion. Current direction:
- Brand:
Agent Colony - Future canonical repo/package name:
pi-agent-colony docs/RENAMING-PLAN.mddocs/RENAME-EXECUTION-CHECKLIST.mddocs/MIGRATION-MATRIX.mddocs/RELEASE-SEQUENCING.md
We are intentionally moving away from defining the product as:
- a bundle of themes, presets, skills, and convenience setup
- an “oh-my-zsh for pi” style wrapper
We now define the core as:
- Ant Colony for Pi
- a multi-agent plugin for complex coding tasks
- a way to give pi scouting, task decomposition, parallel execution, review, and recovery loops
Single-agent execution starts to strain when a task:
- touches 3+ files
- requires cross-module understanding or refactoring
- can be split into parallel sub-tasks
- needs post-execution review and repair loops
Ant Colony is not trying to replace pi. It is trying to give pi a stronger execution layer for tasks that exceed a single agent’s comfort zone.
npx oh-pi # legacy/bootstrap install path during transition
npx pi-agent-colony # canonical install path once published
pi # use colony capabilities inside piFor now, oh-pi still installs and wires everything into ~/.pi/agent/.
The product direction, however, is toward a clearer standalone plugin identity, not a bigger all-in-one configuration bundle.
Ant Colony for Pi is now publishable as a Beta product.
What that means:
- the colony plugin architecture is in place
- core and pi integration boundaries are now physically separated in code
- compatibility wrappers are retained for older import paths
- the main user flows are implemented and tested
What it does not mean yet:
- not a 1.0 / GA claim
- not benchmarked across every provider + environment combination
- not a promise that every user-facing command or internal import path is frozen forever
"Refactor auth from sessions to JWT, add tests, and run a regression pass."
1. scouts inspect the codebase and identify boundaries
2. planners generate a task pool and execution order
3. workers modify separate files or modules in parallel
4. reviewers validate changes and request repairs if needed
5. results are summarized back into the main conversation
That is the real product edge here: complex-task throughput, decomposition quality, and execution reliability.
docs/DEMO-SCRIPT.md— 2-minute walkthroughROADMAP.md— milestones under the new positioningDECISIONS.md— product and architecture trade-offsdocs/PRODUCT.md— product boundary, fit, and non-goalsdocs/ARCHITECTURE-REFACTOR.md— codebase refactor plan for plugin boundaries
Prefer colony for:
- multi-file changes
- cross-module refactors
- new feature decomposition
- test completion, fixes, and regression checks
- engineering work that benefits from parallel execution
Use plain pi workflows when:
- only 1 file needs a clear, contained change
- you need quick Q&A or explanation
- the task requires strict human step-by-step control
- the work is fundamentally non-parallel and highly context-concentrated
~/.pi/agent/
├── auth.json API keys (0600 permissions)
├── settings.json Model, theme, thinking level
├── keybindings.json Vim/Emacs shortcuts (optional)
├── AGENTS.md Role-specific AI guidelines
├── extensions/ 8 extensions (7 default + ant-colony)
│ ├── safe-guard Dangerous command confirmation + path protection
│ ├── git-guard Auto stash checkpoints + dirty repo warning
│ ├── auto-session Session naming from first message
│ ├── custom-footer Enhanced status bar (token/cost/time/git/cwd)
│ ├── compact-header Streamlined startup info
│ ├── auto-update Check for updates on launch
│ ├── bg-process ⏳ **Bg Process** — Auto-background long-running commands (dev servers, etc.)
│ └── ant-colony/ 🐜 Autonomous multi-agent swarm (optional)
├── prompts/ 10 templates (/review /fix /commit /test ...)
├── skills/ 10 skills (tools + UI design + workflows)
└── themes/ 6 custom themes
| Mode | Steps | For |
|---|---|---|
| 🚀 Quick | 3 | Pick provider → enter key → done |
| 📦 Preset | 2 | Choose a role profile → enter key |
| 🎛️ Custom | 6 | Pick everything yourself |
| Theme | Thinking | Includes | |
|---|---|---|---|
| ⚫ Full Power | oh-pi Dark | high | All extensions + bg-process + ant-colony |
| 🔴 Clean | Default | off | No extensions, just core |
| 🐜 Colony Only | oh-pi Dark | medium | Ant-colony with minimal setup |
Anthropic · OpenAI · Google Gemini · Groq · OpenRouter · xAI · Mistral · FOXNIO (recommended public-benefit Claude provider)
Auto-detects API keys from environment variables.
The headline feature. A multi-agent swarm modeled after real ant ecology — deeply integrated into pi's SDK.
You: "Refactor auth from sessions to JWT"
oh-pi:
🔍 Scout ants explore codebase (haiku — fast, cheap)
📋 Task pool generated from discoveries
⚒️ Worker ants execute in parallel (sonnet — capable)
🛡️ Soldier ants review all changes (sonnet — thorough)
✅ Done — report auto-injected into conversation
- Planning Recovery Loop: if scouts return unstructured intel, colony enters
planning_recoveryinstead of failing immediately. - Plan Validation Gate: before workers start, tasks are validated (title/description/caste/priority).
- Scout Quorum for complex goals: multi-step goals default to at least 2 scouts for better planning reliability.
- Thin-entry plugin architecture: real implementations now live in
core/andpi/, with compatibility wrappers preserved. - Background passive progress: colony progress is pushed back into the session without forcing active polling.
SCOUTING → (if needed) PLANNING_RECOVERY → WORKING → REVIEWING → DONE
Each ant is an in-process AgentSession (pi SDK), not a child process:
pi (main process)
└─ ant_colony tool
└─ queen.ts → runColony()
└─ spawnAnt() → createAgentSession()
├─ session.subscribe() → real-time token stream
├─ Zero startup overhead (shared process)
└─ Shared auth & model registry
Interactive mode: Colony runs in the background — you keep chatting. A live widget shows ant progress, and results are auto-injected when done.
Print mode (pi -p): Colony runs synchronously, blocks until complete.
Real ant colonies solve complex problems without central control. Each ant follows simple rules, communicates through pheromone trails, and the colony self-organizes. oh-pi maps this directly:
| Real Ants | oh-pi |
|---|---|
| Scout finds food | Scout scans codebase, identifies targets |
| Pheromone trail | .ant-colony/pheromone.jsonl — shared discoveries |
| Worker carries food | Worker executes task on assigned files |
| Soldier guards nest | Soldier reviews changes, requests fixes |
| More food → more ants | More tasks → higher concurrency (auto-adapted) |
| Pheromone evaporates | 10-minute half-life — stale info fades |
In interactive mode, the colony shows live progress:
- Status bar — compact footer with real metrics: tasks done, active ants, tool calls, output tokens, cost, elapsed time
- Ctrl+Shift+A — overlay detail panel with task list, active ant streams, and colony log
- Notification — completion summary when done
Use /colony-stop to abort a running colony.
The colony communicates with the main conversation via structured signals, so the model never has to guess background state. Updates are passively pushed (non-blocking), so polling is optional:
| Signal | Meaning |
|---|---|
COLONY_SIGNAL:LAUNCHED |
Colony started in background |
COLONY_SIGNAL:SCOUTING |
Scout wave is exploring / planning |
COLONY_SIGNAL:PLANNING_RECOVERY |
Plan recovery loop is restructuring tasks |
COLONY_SIGNAL:WORKING |
Worker phase is executing tasks |
COLONY_SIGNAL:REVIEWING |
Soldier review phase is active |
COLONY_SIGNAL:TASK_DONE |
A task finished (progress checkpoint) |
COLONY_SIGNAL:COMPLETE |
Colony finished and report injected |
COLONY_SIGNAL:FAILED |
Colony failed with diagnostics |
COLONY_SIGNAL:BUDGET_EXCEEDED |
Budget limit reached |
Each ant has a strict turn budget to prevent runaway execution:
Scout: 8 turns · Worker: 15 turns · Soldier: 8 turns
The colony auto-detects available models and lets the LLM pick the best fit per role:
| Role | Strategy | Example |
|---|---|---|
| Scout | Fast & cheap — only reads, no edits | claude-haiku-4-5, gpt-4o-mini |
| Worker | Capable — makes code changes | claude-sonnet-4-0, gpt-4o |
| Soldier | Same as worker or slightly cheaper | claude-sonnet-4-0 |
Omit model overrides to use the current session model for every ant.
| Capability | Status | Notes |
|---|---|---|
Colony tool launch (ant_colony) |
✅ Beta-ready | Background in UI sessions, sync in print/no-UI mode |
| Scout → worker → soldier lifecycle | ✅ Beta-ready | Includes planning recovery and review phase |
| Passive progress signals | ✅ Beta-ready | COLONY_SIGNAL:* follow-up updates |
| Manual snapshot / stop / resume | ✅ Beta-ready | bg_colony_status, /colony-stop, /colony-resume |
| Detail overlay | ✅ Beta-ready | Ctrl+Shift+A |
| Adaptive concurrency | ✅ Beta-ready | CPU / memory / rate-limit aware |
| Checkpoint resume | ✅ Beta-ready | Resumable nest state in .ant-colony/ |
| Import-path compatibility wrappers | ✅ Beta-ready | Root-level wrappers forward to real core/ and pi/ modules |
| Provider coverage across all environments | Core flow works, but broad cross-provider smoke coverage is still limited | |
| Stable long-term plugin API guarantee | Treat current surface as Beta |
The colony tracks cost per ant and total spend, reported in the final summary. Cost never interrupts execution — turn limits and concurrency control handle resource management.
The LLM decides when to deploy the colony. You don't have to think about it:
- ≥3 files need changes → colony
- Parallel workstreams possible → colony
- Single file change → direct execution (no colony overhead)
The colony automatically finds the optimal parallelism for your machine:
Cold start → ceil(max/2) ants (fast ramp-up)
Exploration → +1 each wave, monitoring throughput
Throughput ↓ → lock optimal, stabilize
CPU > 85% → reduce immediately
429 rate limit → -1 concurrency + backoff (2s→5s→10s cap)
Tasks done → scale down to minimum
One ant per file. Always. Conflicting tasks are automatically blocked and resume when locks release.
oh-pi ships 10 skills in three categories.
Zero-dependency Node.js scripts — no API keys needed.
| Skill | What it does |
|---|---|
context7 |
Query latest library docs via Context7 API |
web-search |
DuckDuckGo search (free, no key) |
web-fetch |
Extract webpage content as plain text |
# Examples
./skills/context7/search.js "react"
./skills/web-search/search.js "typescript generics" -n 5
./skills/web-fetch/fetch.js https://example.comComplete design specs with CSS tokens, component examples, and design principles. The agent loads these when you ask for a specific visual style.
| Skill | Style | CSS Prefix |
|---|---|---|
liquid-glass |
Apple WWDC 2025 translucent glass | --lg- |
glassmorphism |
Frosted glass blur + transparency | --glass- |
claymorphism |
Soft 3D clay-like surfaces | --clay- |
neubrutalism |
Bold borders, offset shadows, high contrast | --nb- |
Each includes references/tokens.css with ready-to-use CSS custom properties.
You: "Build a dashboard with liquid glass style"
pi loads liquid-glass skill → applies --lg- tokens, glass effects, specular highlights
| Skill | What it does |
|---|---|
quick-setup |
Detect project type, generate .pi/ config |
debug-helper |
Error analysis, log interpretation, profiling |
git-workflow |
Branching, commits, PRs, conflict resolution |
ant-colony |
Colony management commands and strategies |
| 🌙 oh-pi Dark | Cyan + purple, high contrast |
| 🌙 Cyberpunk | Neon magenta + electric cyan |
| 🌙 Nord | Arctic blue palette |
| 🌙 Catppuccin Mocha | Pastel on dark |
| 🌙 Tokyo Night | Blue + purple twilight |
| 🌙 Gruvbox Dark | Warm retro tones |
/review Code review: bugs, security, performance
/fix Fix errors with minimal changes
/explain Explain code, simple to detailed
/refactor Refactor preserving behavior
/test Generate tests
/commit Conventional Commit message
/pr Pull request description
/security OWASP security audit
/optimize Performance optimization
/document Generate documentation
| Template | Focus |
|---|---|
| General Developer | Universal coding guidelines |
| Full-Stack Developer | Frontend + backend + DB |
| Security Researcher | Pentesting & audit |
| Data & AI Engineer | MLOps & pipelines |
| 🐜 Colony Operator | Multi-agent orchestration |
npx pi-agent-colonyUse this once the canonical package is published.
npx oh-piUse this during the transition window if you still rely on the legacy package name.
pi install npm:pi-agent-colonyLegacy-compatible during transition:
pi install npm:oh-piThis adds themes, prompts, skills, and extensions, including ant-colony.
See pi-package/extensions/ant-colony/README.md for the extension-level layout and direct integration notes.
The current short-term plan is:
- A: make
Agent Colony/Agent Colony for Pithe dominant public name everywhere - B: prepare a full repo/package rename to
pi-agent-colonywith compatibility during migration
Tracking docs:
docs/RENAMING-PLAN.mddocs/RENAME-EXECUTION-CHECKLIST.mddocs/MIGRATION-MATRIX.mddocs/RELEASE-SEQUENCING.mddocs/MIGRATION-ANNOUNCEMENT.md
Canonical install path now:
npx pi-agent-colony
pi install npm:pi-agent-colonyLegacy-compatible transition path:
npx oh-pi
pi install npm:oh-piDetails:
- Node.js ≥ 20
- At least one LLM API key
- pi-coding-agent (installed automatically if missing)
MIT