🐜 oh-pi

<div align="center">

<img src="./logo.svg" width="180" alt="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
```

</div>

---

## 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-organi

... (truncated)