| name | pi-messenger-swarm |
| description | Multi-agent coordination and task orchestration. Run actions via the `pi-messenger-swarm` CLI — a persistent harness server handles all state. Use for swarm coordination, task management, agent messaging, and subagent spawning. |
Pi-Messenger Swarm Skill
Multi-agent coordination via the pi-messenger-swarm CLI.
The CLI auto-spawns a long-lived HTTP server (the harness) on first use. Every call dispatches an action to the harness, which holds persistent state — agent registrations, task store, feed — across calls.
- No fixed planner/worker/reviewer roles
- Any joined or spawned agent can create/claim/complete tasks
- When you spawn agents for tasks, act as coordinator — delegate, don't hoard
Setup
If installed globally (npm install -g pi-messenger-swarm), the pi-messenger-swarm command is on your PATH. Otherwise, the extension installs a shell wrapper script at ~/.pi/agent/bin/pi-messenger-swarm which pi adds to PATH automatically — no manual setup needed.
Agent identity is resolved by the CLI using the PI_AGENT_NAME environment variable (set by the parent on spawn). The CLI sends this to the harness server, which matches it against registrations on disk. If PI_AGENT_NAME is not set (e.g., human terminal), the CLI falls back to walking the process tree to find the parent pi process PID.
pi-messenger-swarm join
pi-messenger-swarm task list
pi-messenger-swarm swarm
Core protocol
- Join first
pi-messenger-swarm join
- Inspect swarm state
pi-messenger-swarm swarm
pi-messenger-swarm task list
- Delegate before claiming
If you spawned subagents for specific tasks, do not claim those tasks yourself — your spawned agents will claim and execute them. Only claim tasks you intend to implement personally (typically tasks you did not delegate).
pi-messenger-swarm spawn --task-id task-1 --role Debugger "Fix the race condition"
- Claim only tasks you will implement yourself
pi-messenger-swarm task claim task-1
- Reserve files before edits
pi-messenger-swarm reserve src/auth/ --reason task-1
- Log progress and complete
pi-messenger-swarm task progress task-1 "Implemented JWT verification"
pi-messenger-swarm task done task-1 "Auth middleware + tests"
pi-messenger-swarm release
Command reference
Coordination
pi-messenger-swarm join [--channel dev] [--create]
pi-messenger-swarm status
pi-messenger-swarm list
pi-messenger-swarm channels [--all]
pi-messenger-swarm feed [--limit 20] [--channel dev]
pi-messenger-swarm send AgentName "hello"
pi-messenger-swarm send
pi-messenger-swarm reserve src/ --reason task-1
pi-messenger-swarm release
pi-messenger-swarm whois AgentName
pi-messenger-swarm set-status "debugging auth"
pi-messenger-swarm rename NewName
Swarm board
pi-messenger-swarm swarm [--channel dev]
Task operations
pi-messenger-swarm task list
pi-messenger-swarm task ready
pi-messenger-swarm task stalled
pi-messenger-swarm task show task-3
pi-messenger-swarm task stalled
pi-messenger-swarm task create --title "Fix token refresh race"
pi-messenger-swarm task create --title "..." --content "..." --depends-on task-2
pi-messenger-swarm task claim task-3
pi-messenger-swarm task unclaim task-3
pi-messenger-swarm task progress task-3 "Fixed the race"
pi-messenger-swarm task done task-3 "Auth middleware + tests"
pi-messenger-swarm task block task-3 --reason "Awaiting API key"
pi-messenger-swarm task unblock task-3
pi-messenger-swarm task reset task-3 [--cascade]
pi-messenger-swarm task archive-done
Dynamic subagent spawning
pi-messenger-swarm spawn --role Researcher "Analyze competitor X"
pi-messenger-swarm spawn --role Analyst --persona "Skeptical market researcher" "Find productization gaps"
pi-messenger-swarm spawn --task-id task-1 --role Debugger "Fix the race condition"
pi-messenger-swarm spawn --agent-file agents/researcher.md "Analyze the codebase"
pi-messenger-swarm spawn --objective "Find bugs" --context "Focus on auth" --role Auditor "Review code"
pi-messenger-swarm spawn --message-file /tmp/mission.txt --role Researcher
pi-messenger-swarm spawn list
pi-messenger-swarm spawn history
pi-messenger-swarm spawn stop <id>
Shell safety: When mission text contains backticks, ${...}, parentheses, or other shell-sensitive characters, use --message-file <path> instead of a positional argument. Write the prompt to a temp file first to avoid bash interpolation corrupting the mission text.
Agent file format
--agent-file points to a markdown file with optional YAML frontmatter. The frontmatter supplies role/persona/model/objective defaults; the body after --- becomes the system prompt.
---
role: Security Reviewer
persona: Paranoid about edge cases
objective: Review code for security vulnerabilities
---
You are a security expert. Focus on input validation and auth boundaries.
Frontmatter fields (all optional):
| Field | Purpose |
|---|
role | Agent role label (default: Subagent) |
persona | Tone/behavior modifier |
model | Default model (overridable at spawn time) |
objective | Default mission (overridable via CLI text) |
If the file has no frontmatter, the entire file content is used as the system prompt with role defaulting to Subagent.
CLI flags override frontmatter values — for example, --role overrides role:, and positional mission text overrides objective:.
Server management
| Command | Behavior |
|---|
pi-messenger-swarm --status | Print health JSON or exit 1 |
pi-messenger-swarm --start | Start the harness server |
pi-messenger-swarm --stop | Graceful shutdown |
pi-messenger-swarm --restart | Soft restart: clear caches, preserve agents |
pi-messenger-swarm --logs | tail -f the server log |
JSON passthrough
For programmatic use or complex actions, JSON is still accepted:
pi-messenger-swarm '{ "action": "join", "channel": "dev" }'
pi-messenger-swarm '{ "action": "spawn", "role": "Researcher", "message": "Analyze X", "taskId": "task-1" }'
Swarm Philosophy
The swarm is self-organizing. Your role is participant, not manager.
Pull-based, not push-based
Messages and state changes are written to the channel feed. Nobody pushes them to you — you must read the feed yourself between turns.
pi-messenger-swarm feed --limit 10
This is kafka-like: channels are durable logs, agents subscriibe by reading. If a teammate sent you a message, you'll find it in the feed. If you don't read it, it sits there until you do.
Good pattern: read the feed at decision points, then act.
- Before claiming: check what's ready
- After spawning: trust the agent to execute
- On uncertainty: read the feed, then message the agent directly
- Periodically: check for stalled tasks that need re-delegation
Spawn-and-delegate, don't hoard
When you spawn subagents, you are the coordinator. You create the tasks, spawn the agents, then step back. Let the agents claim and execute their assigned work — do not claim those tasks yourself.
Your role after spawning:
- Monitor progress via
pi-messenger-swarm swarm or pi-messenger-swarm feed
- Unblock agents when they hit problems (share context, clarify scope)
- Handle only tasks you did not delegate to a subagent
Anti-pattern: spawning agents then claiming all tasks yourself. This leaves spawned agents idle with nothing to do.
Collaborate, don't micromanage
Subagents execute with full context. They report progress through task updates and messaging. Stay available for collaboration without inserting yourself into their loop.
Engage when:
- They reach out with a question or blocker
- You have relevant context they lack (share it proactively)
- Output reveals a misunderstanding of constraints
- The work naturally intersects with yours
Let them own their execution. Your value is in strategic context and unblocking, not status checks.
Reading agent output
The feed (pi-messenger-swarm feed) shows one-line previews. For full findings and detail, use:
pi-messenger-swarm task show task-1
Agents are instructed to write all findings into task progress and task done messages — not just their response text — so everything is in the task record.
Storage layout
Swarm data is project-scoped by default (isolated per project):
.pi/messenger/
├── channels/
│ └── <channel>.jsonl # Metadata header (line 1) + feed events
├── tasks/ # Task event JSONL (per session)
│ └── <session>.jsonl
├── agents/ # Spawn event JSONL (per session)
│ └── <session>.jsonl
└── locks/ # Race-safe coordination locks
Override locations
PI_MESSENGER_DIR=/path/to/dir pi
PI_MESSENGER_GLOBAL=1 pi
