oh-pi logo # 🐜 oh-pi **One command to supercharge [pi-coding-agent](https://github.com/badlogic/pi-mono).** Like oh-my-zsh for pi β€” but with an autonomous ant colony. [![npm](https://img.shields.io/npm/v/oh-pi)](https://www.npmjs.com/package/oh-pi) [![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 ```
--- ## 30-Second Start ```bash npx oh-pi # configure everything pi # start coding ``` oh-pi auto-detects your environment, guides setup in a modern TUI, and writes `~/.pi/agent/` for you. Already configured? It detects existing files and offers **backup before overwriting**. ## 2-Minute Value pi-coding-agent is powerful by default, but manual setup across providers, themes, extensions, skills, and prompts is slow. oh-pi compresses that setup into under a minute β€” then adds an **ant colony swarm** for multi-agent execution. Want the fast walkthrough? See [`docs/DEMO-SCRIPT.md`](./docs/DEMO-SCRIPT.md). ## When Not to Use Ant Colony Use plain pi workflows (without colony) when your task is tiny, highly exploratory, or needs constant human steering. For positioning, scope, and milestones, see [`ROADMAP.md`](./ROADMAP.md). For rationale behind key trade-offs, see [`DECISIONS.md`](./DECISIONS.md). ## What You Get ``` ~/.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/ 11 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 v0.1.75 - **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. ### 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. ### 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 11 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 | ## Also a Pi Package Skip the configurator, just install the resources: ```bash pi install npm:oh-pi ``` Adds all themes, prompts, skills, and extensions to your existing pi setup. ## Requirements - Node.js β‰₯ 20 - At least one LLM API key - pi-coding-agent (installed automatically if missing) ## License MIT