🐜 Ant Colony — Multi-Agent Swarm Extension

A self-organizing multi-agent system modeled after real ant colony ecology. Adaptive concurrency, pheromone communication, zero centralized scheduling.

Architecture

Queen                           Main pi process, receives goals, orchestrates lifecycle
  │
  ├─ 🔍 Scout                   Lightweight haiku, explores paths, marks food sources
  ├─ ⚒️  Worker                  Sonnet, executes tasks, may spawn sub-tasks
  └─ 🛡️ Soldier                 Sonnet, reviews quality, may request rework

Pheromone                       Shared ant-colony state store, indirect ant-to-ant communication
Nest                            Shared state, atomic file operations, cross-process safe

Lifecycle

Goal → Scouting → Task Pool → Workers Execute in Parallel → Soldiers Review → Fix (if needed) → Done
          │                           │
          │  Pheromone decay (10min)   │  Sub-tasks auto-spawned
          └───────────────────────────┘

Workspace Isolation (Default)

Ant-colony stores runtime state outside the repository by default under the shared pi agent directory, mirroring the workspace path so each repo gets its own isolated storage root. Project-local .ant-colony/ storage remains available as an explicit opt-in for legacy workflows.

Resolve the parent directory for isolated colony worktrees. Shared mode keeps them under the workspace-mirrored shared root in worktrees/, while project mode places them under the legacy project-local .ant-colony/worktrees/ path.

Shared storage layout:

~/.pi/agent/ant-colony/root/<mirrored-workspace-path>/
└── colonies/

~/.pi/agent/worktrees/root/<mirrored-repo-root>/worktrees/
└── ant-colony-...

Prepare the execution workspace for a colony run. When worktree isolation is enabled and git supports it, the colony gets a fresh isolated worktree on an ant-colony/... branch; otherwise it falls back to the shared working directory and records the reason.

You can disable worktree isolation with:

PI_ANT_COLONY_WORKTREE=0

Resolve the effective ant-colony storage mode and shared root. Explicit options win, then environment variables, then extension config, and shared storage is the default when no override is provided.

You can opt back into project-local storage if you want the legacy behavior:

// ~/.pi/agent/extensions/ant-colony/config.json
{
	"storageMode": "project"
}

Optional overrides:

PI_ANT_COLONY_STORAGE_MODE=shared
PI_ANT_COLONY_STORAGE_ROOT=~/.pi/agent/ant-colony

Adaptive Concurrency

Models real ant colony dynamic recruitment:

• Cold start: 1–2 ants, gradual exploration
• Exploration phase: +1 each wave, monitoring throughput inflection point
• Steady state: fine-tune around optimal value
• Overload protection: CPU > 85% or memory < 500MB → auto-reduce
• Elastic scaling: more tasks → recruit; fewer tasks → shrink

Usage

Auto-Trigger

The LLM automatically invokes the ant_colony tool when task complexity warrants it.

Commands

/colony <goal>              Start a new colony for the given goal
/colony-count               Show number of currently running colonies
/colony-status [id]         Show running colonies (runtime cN or stable colony-... ID)
/colony-stop [id|all]       Cancel one running colony (runtime/stable ID) or all
/colony-resume [colonyId]   Resume a specific stable colony ID, or all resumable by default
Ctrl+Shift+A                Open colony details panel

Examples

/colony Migrate the entire project from CommonJS to ESM, updating all imports/exports and tsconfig

/colony Add unit tests for all modules under src/, targeting 80% coverage

/colony Refactor auth system from session-based to JWT, maintaining API compatibility

Delegated Routing Categories

When @ifi/pi-extension-adaptive-routing is installed, colony castes and worker classes can resolve models from delegated startup categories in ~/.pi/agent/extensions/adaptive-routing/config.json.

Default categories:

• scout → quick-discovery
• worker/backend → implementation-default
• soldier/review → review-critical
• design → visual-engineering
• multimodal → multimodal-default

Explicit ant_colony model overrides still win over delegated routing.

When no explicit override is present, the delegated selector uses the currently available models, optional delegatedModelSelection disable lists and role overrides (for example colony:scout or colony:review), usage headroom when available, context-window fit, and benchmark-backed task scores to choose a model.

To inspect a delegated colony pick, use @ifi/pi-extension-adaptive-routing's /route why <category|role-override> [task text] command.

Usage Tracking Integration

Ant inference usage (tokens + cost) is streamed to the usage-tracker extension via pi.events (usage:record). So /usage, usage_report, and session cost totals now include background colony inference, making colony spend visible.

Pheromone System

Ants communicate indirectly through pheromones (stigmergy), not direct messages:

| Type | Released By | Meaning | | ---------- | ----------- | --------------------------------------- | | discovery | Scout | Discovered code structure, dependencies | | progress | Worker | Completed changes, file modifications | | warning | Soldier | Quality issues, conflict risks | | completion | Worker | Task completion marker | | dependency | Any | File dependency relationships |

Pheromones decay exponentially (10-minute half-life), preventing stale info from misleading subsequent ants.

File Locking

Each task declares the files it operates on. The queen guarantees:

• Only one ant modifies a given file at any time
• Conflicting tasks are automatically marked blocked and resume when locks release

Nest Structure

Resolve the parent directory for persisted colony state. Shared mode stores state under the workspace-mirrored shared root in colonies/, while project mode keeps using the legacy local .ant-colony/ directory.

~/.pi/agent/ant-colony/root/<mirrored-workspace-path>/colonies/{colony-id}/
├── state.json           Colony state
├── pheromone.jsonl      Append-only pheromone log
└── tasks/               One file per task (atomic updates)
    ├── t-xxx.json
    └── t-yyy.json

Best-effort migration for legacy project-local colony state. When shared mode is active, existing .ant-colony/{colony-id}/ directories are copied into the shared store so resumable colonies keep working without leaving runtime state in the repo.

Installation

# Install just ant-colony
pi install npm:@ifi/oh-pi-ant-colony

# Or install the full oh-pi bundle (includes ant-colony)
pi install npm:@ifi/oh-pi

Then start pi:

pi

Module Reference

| File | Lines | Responsibility | | ---------------- | ----- | -------------------------------------------------------------------------- | | types.ts | ~150 | Type system: ants, tasks, pheromones, colony state | | nest.ts | ~500 | Nest: file-system shared state, atomic R/W, pheromone decay | | concurrency.ts | ~120 | Adaptive concurrency: system sampling, exploration/steady-state adjustment | | spawner.ts | ~420 | Ant spawning: session lifecycle, usage streaming, prompt/output handling | | queen.ts | ~1020 | Queen scheduling: lifecycle, task waves, multi-round iteration | | worktree.ts | ~180 | Git worktree isolation and resume workspace recovery helpers | | index.ts | ~1050 | Extension entry: tool/shortcut registration, TUI rendering, status signals | | deps.ts | ~140 | Lightweight import graph for dependency-aware scheduling | | parser.ts | ~180 | Sub-task and pheromone extraction from ant output | | prompts.ts | ~90 | Per-caste system prompts and prompt builder | | ui.ts | ~140 | Formatting helpers for status bar, overlay, and reports |