oh-pi logo # 🐜 Ant Colony for Pi **Turn [pi-coding-agent](https://github.com/badlogic/pi-mono) 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**. [![npm](https://img.shields.io/npm/v/pi-agent-colony)](https://www.npmjs.com/package/pi-agent-colony) [![license](https://img.shields.io/npm/l/oh-pi)](./LICENSE) [![node](https://img.shields.io/node/v/oh-pi)](https://nodejs.org) [English](./README.md) | [δΈ­ζ–‡](./README.zh.md) | [FranΓ§ais](./README.fr.md) ```bash npx oh-pi # or, once the canonical package is published: npx pi-agent-colony ```
--- ## Naming Clarification This 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.md`](./docs/RENAMING-PLAN.md) - [`docs/RENAME-EXECUTION-CHECKLIST.md`](./docs/RENAME-EXECUTION-CHECKLIST.md) - [`docs/MIGRATION-MATRIX.md`](./docs/MIGRATION-MATRIX.md) - [`docs/RELEASE-SEQUENCING.md`](./docs/RELEASE-SEQUENCING.md) ## New Positioning ### This is no longer framed as a β€œconfiguration mega-pack” 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** ### What problem it solves 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. ## 30-Second Start ```bash npx oh-pi # legacy/bootstrap install path during transition npx pi-agent-colony # canonical install path once published pi # use colony capabilities inside pi ``` For 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. ## Release Status **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 ## See the colony value first ### If you say ```text "Refactor auth from sessions to JWT, add tests, and run a regression pass." ``` ### Ant Colony responds like this ```text 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`](./docs/DEMO-SCRIPT.md) β€” 2-minute walkthrough - [`ROADMAP.md`](./ROADMAP.md) β€” milestones under the new positioning - [`DECISIONS.md`](./DECISIONS.md) β€” product and architecture trade-offs - [`docs/PRODUCT.md`](./docs/PRODUCT.md) β€” product boundary, fit, and non-goals - [`docs/ARCHITECTURE-REFACTOR.md`](./docs/ARCHITECTURE-REFACTOR.md) β€” codebase refactor plan for plugin boundaries ## When to Use Ant Colony 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 ## When Not to Use Ant Colony 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 ## What This Repo Currently Contains ``` ~/.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 ``` ## Setup Modes | Mode | Steps | For | |------|-------|-----| | πŸš€ **Quick** | 3 | Pick provider β†’ enter key β†’ done | | πŸ“¦ **Preset** | 2 | Choose a role profile β†’ enter key | | πŸŽ›οΈ **Custom** | 6 | Pick everything yourself | ### Presets | | 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 | ### Providers Anthropic Β· OpenAI Β· Google Gemini Β· Groq Β· OpenRouter Β· xAI Β· Mistral Β· [FOXNIO](https://www.foxnio.com) (recommended public-benefit Claude provider) Auto-detects API keys from environment variables. ## 🐜 Ant Colony 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 ``` ### What's new in the current Beta line - **Planning Recovery Loop**: if scouts return unstructured intel, colony enters `planning_recovery` instead 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/` and `pi/`, with compatibility wrappers preserved. - **Background passive progress**: colony progress is pushed back into the session without forcing active polling. ### Colony lifecycle (simple) `SCOUTING β†’ (if needed) PLANNING_RECOVERY β†’ WORKING β†’ REVIEWING β†’ DONE` ### Architecture 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. ### Why ants? 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 | ### Real-time UI 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. ### Signal Protocol 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 | ### Turn Control Each ant has a strict turn budget to prevent runaway execution: Scout: 8 turns Β· Worker: 15 turns Β· Soldier: 8 turns ### Model Selection 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. ## Beta Capability Matrix | 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 | ⚠️ Partial | Core flow works, but broad cross-provider smoke coverage is still limited | | Stable long-term plugin API guarantee | ⚠️ Not yet | Treat current surface as Beta | ### Cost Reporting 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. ### Auto-trigger 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) ### Adaptive Concurrency 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 ``` ### File Safety One ant per file. Always. Conflicting tasks are automatically blocked and resume when locks release. ## Skills oh-pi ships 10 skills in three categories. ### πŸ”§ Tool Skills 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 | ```bash # Examples ./skills/context7/search.js "react" ./skills/web-search/search.js "typescript generics" -n 5 ./skills/web-fetch/fetch.js https://example.com ``` ### 🎨 UI Design System Skills Complete 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 ``` ### πŸ”„ Workflow Skills | 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 | ## Themes | | | |---|---| | πŸŒ™ **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 | ## Prompt Templates ``` /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 ``` ## AGENTS.md Templates | 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 | ## Install Paths ### Option 1: canonical bootstrap install ```bash npx pi-agent-colony ``` Use this once the canonical package is published. ### Option 2: legacy/bootstrap compatibility install ```bash npx oh-pi ``` Use this during the transition window if you still rely on the legacy package name. ### Option 3: install as a Pi package ```bash pi install npm:pi-agent-colony ``` Legacy-compatible during transition: ```bash pi install npm:oh-pi ``` This adds themes, prompts, skills, and extensions, including `ant-colony`. ### Option 4: use the extension source directly See [`pi-package/extensions/ant-colony/README.md`](./pi-package/extensions/ant-colony/README.md) for the extension-level layout and direct integration notes. ## Rename Transition The current short-term plan is: - **A:** make `Agent Colony` / `Agent Colony for Pi` the dominant public name everywhere - **B:** prepare a full repo/package rename to `pi-agent-colony` with compatibility during migration Tracking docs: - [`docs/RENAMING-PLAN.md`](./docs/RENAMING-PLAN.md) - [`docs/RENAME-EXECUTION-CHECKLIST.md`](./docs/RENAME-EXECUTION-CHECKLIST.md) - [`docs/MIGRATION-MATRIX.md`](./docs/MIGRATION-MATRIX.md) - [`docs/RELEASE-SEQUENCING.md`](./docs/RELEASE-SEQUENCING.md) - [`docs/MIGRATION-ANNOUNCEMENT.md`](./docs/MIGRATION-ANNOUNCEMENT.md) ## Migration Announcement Canonical install path now: ```bash npx pi-agent-colony pi install npm:pi-agent-colony ``` Legacy-compatible transition path: ```bash npx oh-pi pi install npm:oh-pi ``` Details: - [`docs/MIGRATION-ANNOUNCEMENT.md`](./docs/MIGRATION-ANNOUNCEMENT.md) ## Release Artifacts - [Release checklist](./RELEASE-CHECKLIST.md) - [Changelog](./CHANGELOG.md) - [Release notes for v0.1.86](./RELEASE-NOTES-v0.1.86.md) - [Release notes for v0.1.85](./RELEASE-NOTES-v0.1.85.md) ## Requirements - Node.js β‰₯ 20 - At least one LLM API key - pi-coding-agent (installed automatically if missing) ## License MIT