🐜 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                       .ant-colony/ file system, 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
          └───────────────────────────┘

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-stop                Cancel a running colony
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

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

.ant-colony/{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

Installation

# Option 1: Symlink to pi extensions directory
mkdir -p ~/.pi/agent/extensions/ant-colony
ln -sf "$(pwd)/pi-package/extensions/ant-colony/index.ts" ~/.pi/agent/extensions/ant-colony/index.ts
# ... (symlink all .ts files)

# Option 2: Install via oh-pi
npx oh-pi  # Select "Full Power" preset

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	~370	Ant spawning: session management, prompt construction, output parsing
queen.ts	~1000	Queen scheduling: lifecycle, task waves, multi-round iteration
index.ts	~900	Extension entry: tool/shortcut registration, TUI rendering
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