pi-messenger

Pi Messenger

What if multiple agents in different terminals sharing a folder could talk to each other like they're in a chat room? Join, see who's online and what they're doing. Claim tasks, reserve files, send messages. An extension for Pi coding agent — install it and go. No daemon, no server, just files.

Installation

pi install npm:pi-messenger

Crew agents ship with the extension (crew/agents/*.md) and are discovered automatically. The pi-messenger-crew skill is auto-loaded from the extension. Workers can load domain-specific crew skills on demand during task execution.

To show available crew agents:

npx pi-messenger --crew-install

To customize an agent for one project, copy it to .pi/messenger/crew/agents/ and edit it.

To remove the extension:

npx pi-messenger --remove

To remove stale crew agent copies from the shared legacy directory (~/.pi/agent/agents/):

npx pi-messenger --crew-uninstall

Quick Start

Once joined (manually or via autoRegister config), agents can coordinate:

pi_messenger({ action: "join" })
pi_messenger({ action: "reserve", paths: ["src/auth/"], reason: "Refactoring" })
pi_messenger({ action: "send", to: "GoldFalcon", message: "auth is done" })
pi_messenger({ action: "release" })

For multi-agent task orchestration from a PRD:

pi_messenger({ action: "plan" })                       // Planner analyzes codebase, creates tasks
pi_messenger({ action: "work", autonomous: true })      // Workers execute tasks in waves until done
pi_messenger({ action: "review", target: "task-1" })    // Reviewer checks implementation

Features

Living Presence - Status indicators (active, idle, away, stuck), tool call counts, token usage, and auto-generated status messages like "on fire" or "debugging...". Your agent name appears in the status bar: msg: SwiftRaven (2 peers) ●3

Activity Feed - Unified timeline of edits, commits, test runs, messages, and task events. Query with { action: "feed" }.

Discovery - Agents register with memorable themed names (SwiftRaven, LunarDust, OakTree). See who's active, what they're working on, which model and git branch they're on.

Messaging - Send messages between agents. Recipients wake up immediately and see the message as a steering prompt.

File Reservations - Claim files or directories. Other agents get blocked with a clear message telling them who to coordinate with. Auto-releases on exit.

Stuck Detection - Agents idle too long with an open task or reservation are flagged as stuck. Peers get a notification.

Human as Participant - Your interactive pi session appears in the agent list with (you). Same activity tracking, same status messages. Chat from the overlay.

Chat Overlay

/messenger opens an interactive overlay with agent presence, activity feed, and chat:

Chat input supports @Name msg for DMs and @all msg for broadcasts. Text without @ broadcasts from the Agents tab or DMs the selected agent tab.

Key	Action
Tab / ← →	Switch tabs (Agents, Crew, agent DMs, All)
↑ ↓	Scroll history / navigate crew tasks
Enter	Send message
Esc	Close

Crew: Task Orchestration

Crew turns a PRD into a dependency graph of tasks, then executes them in parallel waves.

Crew logs are per project, under that project's working directory: .pi/messenger/crew/. For example, if you run Crew from /path/to/my-app, the planner log lives at /path/to/my-app/.pi/messenger/crew/planning-progress.md.

Workflow

• Plan — Planner explores the codebase and PRD, drafts tasks with dependencies. A reviewer checks the plan; the planner refines until SHIP or maxPasses is reached. History is stored in planning-progress.md.
• Work — Workers implement ready tasks (all dependencies met) in parallel waves. A single work call runs one wave. autonomous: true runs waves back-to-back until everything is done or blocked. Each completed task gets an automatic reviewer pass — SHIP keeps it done, NEEDS_WORK resets it for retry with feedback, MAJOR_RETHINK blocks it. Controlled by review.enabled and review.maxIterations.
• Review — Manual review of a specific task or the plan: pi_messenger({ action: "review", target: "task-1" }). Returns SHIP, NEEDS_WORK, or MAJOR_RETHINK with detailed feedback.

No special PRD format required — the planner auto-discovers PRD.md, SPEC.md, DESIGN.md, etc. in your project root and docs/. Or skip the file entirely:

pi_messenger({ action: "plan", prompt: "Scan the codebase for bugs" })

// Plan + auto-start autonomous work when planning completes
pi_messenger({ action: "plan" })  // auto-starts workers (default)

Wave Execution

Tasks form a dependency graph. Independent tasks run concurrently:

Wave 1:  task-1 (no deps)  ─┐
         task-3 (no deps)  ─┤── run in parallel
                             │
Wave 2:  task-2 (→ task-1) ─┤── task-1 done, task-2 unblocked
         task-4 (→ task-3) ─┘── task-3 done, task-4 unblocked

Wave 3:  task-5 (→ task-2, task-4) ── both deps done

The planner structures tasks to maximize parallelism. Foundation work has no dependencies and starts immediately. Features that don't touch each other get separate chains. Autonomous mode stops when all tasks are done or blocked.

Crew Skills

Workers follow the same join/read/implement/commit/release protocol regardless of the task — what changes between tasks is domain knowledge. Crew skills let workers acquire that knowledge on demand.

Skills are discovered from three locations (later sources override earlier by name):

• User skills — ~/.pi/agent/skills/ (pi's standard dir/SKILL.md format)
• Extension skills — crew/skills/ within the extension (flat .md files)
• Project skills — .pi/messenger/crew/skills/ in your project root (flat .md files)

The planner sees a compact index of all discovered skills and can tag tasks with relevant ones. Workers see tagged skills as "Recommended for this task" with the full catalog under "Also available", and load what they need via read(). Zero tokens spent until a worker actually needs the knowledge.

To add a project-level skill, drop a .md file in .pi/messenger/crew/skills/:

---
name: our-api-patterns
description: REST API conventions for this project — auth, pagination, error shapes.
---

# API Patterns

Always use Bearer token auth. Paginate with cursor-based `?after=` params.
Error responses use `{ error: { code, message, details? } }` shape.

Any skills you already have in ~/.pi/agent/skills/ are automatically available to crew workers — no setup needed.

Crew Configuration

Crew spawns multiple LLM sessions in parallel — it can burn tokens fast. Start with a cheap worker model and scale up once you've seen the workflow. Add this to ~/.pi/agent/pi-messenger.json:

{ "crew": { "models": { "worker": "claude-haiku-4-5" } } }

The planner and reviewer keep their frontmatter defaults; only workers (the bulk of the spend) get the cheap model. Override per-role as needed:

{
  "crew": {
    "models": {
      "worker": "claude-haiku-4-5",
      "planner": "claude-sonnet-4-6",
      "reviewer": "claude-sonnet-4-6"
    }
  }
}

Model strings accept provider/model format for explicit provider selection and :level suffix for inline thinking control. These work anywhere a model is specified — config, frontmatter, or per-task override:

{
  "crew": {
    "models": {
      "worker": "anthropic/claude-haiku-4-5",
      "planner": "openrouter/anthropic/claude-sonnet-4:high"
    }
  }
}

The :level suffix and the thinking.<role> config are independent — if both are set, the suffix takes precedence and the --thinking flag is skipped to avoid double-application.

Full config reference (all fields optional — only set what you want to change):

{
  "crew": {
    "concurrency": { "workers": 2, "max": 10 },
    "coordination": "chatty",
    "models": { "worker": "claude-haiku-4-5" },
    "review": { "enabled": true, "maxIterations": 3 },
    "planning": { "maxPasses": 1 },
    "work": {
      "maxAttemptsPerTask": 5,
      "maxWaves": 50
    }
  }
}

Setting	Description	Default
concurrency.workers	Default parallel workers per wave	2
concurrency.max	Maximum workers allowed (hard ceiling is 10)	10
dependencies	Dependency scheduling mode: advisory or strict	"advisory"
coordination	Worker coordination level: none, minimal, moderate, chatty	"chatty"
messageBudgets	Max outgoing messages per worker per level (sends rejected after limit)	{ none: 0, minimal: 2, moderate: 5, chatty: 10 }
models.planner	Model for planner agent	anthropic/claude-opus-4-6
models.worker	Model for workers (overridden by per-task or per-wave model param)	anthropic/claude-haiku-4-5
models.reviewer	Model for reviewer agent	anthropic/claude-opus-4-6
models.analyst	Model for analyst (plan-sync) agent	anthropic/claude-haiku-4-5
thinking.planner	Thinking level for planner agent	(from frontmatter)
thinking.worker	Thinking level for worker agents	(from frontmatter)
thinking.reviewer	Thinking level for reviewer agents	(from frontmatter)
thinking.analyst	Thinking level for analyst agents	(from frontmatter)
review.enabled	Auto-review after task completion	true
review.maxIterations	Max review/fix cycles per task	3
planning.maxPasses	Max planner/reviewer refinement passes	1
work.maxAttemptsPerTask	Auto-block after N failures	5
work.maxWaves	Max autonomous waves	50
work.shutdownGracePeriodMs	Grace period before SIGTERM on abort	30000
work.env	Environment variables passed to spawned workers	{}

Default Agent Models

Each crew agent ships with a default model in its frontmatter. Override any of these via crew.models.<role> in config:

Agent	Role	Default Model
crew-planner	planner	anthropic/claude-opus-4-6
crew-worker	worker	anthropic/claude-haiku-4-5
crew-reviewer	reviewer	anthropic/claude-opus-4-6
crew-plan-sync	analyst	anthropic/claude-haiku-4-5

Agent definitions live in crew/agents/ within the extension. To customize one for a project, copy it to .pi/messenger/crew/agents/ and edit the frontmatter — project-level agents override extension defaults by name. Agents support thinking: <level> in frontmatter (off, minimal, low, medium, high, xhigh). Config thinking.<role> overrides the frontmatter value.

API Reference

Coordination

Action	Description
join	Join the agent mesh
list	List agents with presence info
status	Show your status or crew progress
whois	Detailed info about an agent (name required)
feed	Show activity feed (limit optional, default: 20)
set_status	Set custom status message (message optional — omit to clear)
send	Send DM (to + message required)
broadcast	Broadcast to all (message required)
reserve	Reserve files (paths required, reason optional)
release	Release reservations (paths optional — omit to release all)
rename	Change your name (name required)

Crew

Action	Description
plan	Create plan from PRD or inline prompt (prd, prompt optional — auto-discovers PRD if omitted, auto-starts workers unless autoWork: false)
work	Run ready tasks (autonomous, concurrency optional)
review	Review implementation (target task ID required)
task.list	List all tasks
task.show	Show task details (id required)
task.start	Start a task (id required)
task.done	Complete a task (id required, summary optional)
task.block	Block a task (id + reason required)
task.unblock	Unblock a task (id required)
task.ready	List tasks ready to work
task.reset	Reset a task (id required, cascade optional)
crew.status	Overall crew status
crew.validate	Validate plan dependencies
crew.agents	List available crew agents
crew.install	Show discovered crew agents and their sources
crew.uninstall	Remove stale shared-directory crew agent copies

Swarm (Spec-Based)

Action	Description
swarm	Show swarm task status
claim	Claim a task (taskId required)
unclaim	Release a claim (taskId required)
complete	Complete a task (taskId required)

Configuration

Create ~/.pi/agent/pi-messenger.json:

{
  "autoRegister": false,
  "autoRegisterPaths": ["~/projects/team-collab"],
  "scopeToFolder": false,
  "nameTheme": "default",
  "stuckThreshold": 900,
  "stuckNotify": true,
  "autoOverlayPlanning": true
}

Setting	Description	Default
autoRegister	Join mesh on startup	false
autoRegisterPaths	Folders where auto-join is enabled (supports * globs)	[]
scopeToFolder	Only see agents in same directory	false
nameTheme	Name theme: default, nature, space, minimal, custom	"default"
nameWords	Custom theme words: { adjectives: [...], nouns: [...] }	—
feedRetention	Max events kept in activity feed	50
stuckThreshold	Seconds of inactivity before stuck detection	900
stuckNotify	Show notification when a peer appears stuck	true
autoStatus	Auto-generate status messages from activity	true
autoOverlay	Auto-open overlay when autonomous crew work starts	true
autoOverlayPlanning	Auto-open Crew overlay when planning starts or is restored in-progress	true
crewEventsInFeed	Include crew task events in activity feed	true
contextMode	Context injection level: full, minimal, none	"full"

Config priority: project .pi/pi-messenger.json > user ~/.pi/agent/pi-messenger.json > ~/.pi/agent/settings.json "messenger" key > defaults.

How It Works

Pi-messenger is a pi extension that hooks into the agent lifecycle. It uses pi.on("tool_call") and pi.on("tool_result") to track activity — every edit, commit, and test run gets logged. pi.on("session_start") handles auto-registration, pi.on("session_shutdown") cleans up, and pi.on("agent_end") drives autonomous crew mode by checking for ready tasks after each agent turn.

Incoming messages wake the receiving agent via pi.sendMessage() with triggerTurn: true and deliverAs: "steer", which injects the message as a steering prompt that resumes the agent. File reservations are enforced by returning { block: true } from a tool_call hook on write/edit operations. The /messenger overlay uses ctx.ui.custom() for the chat TUI, and ctx.ui.setStatus() keeps the status bar updated with peer count and unread messages.

Crew workers are spawned as pi --mode json subprocesses with the agent's system prompt, model, and tool restrictions from their .md definitions. Progress is tracked via JSONL streaming — the overlay subscribes to a live progress store that shows each worker's current tool, call count, and token usage in real time. Aborting a work run triggers graceful shutdown: each worker receives an inbox message asking it to stop, followed by a grace period before SIGTERM. The planner and reviewer work the same way — just pi instances with different agent configs.

All coordination is file-based, no daemon required. Shared state (registry, inboxes, swarm claims/completions) lives in ~/.pi/agent/messenger/. Activity feed and crew data are project-scoped under .pi/messenger/ inside your project, so Crew logs live at <project>/.pi/messenger/crew/ and the shared activity feed lives at <project>/.pi/messenger/feed.jsonl. Dead agents are detected via PID checks and cleaned up automatically.

Credits

• mcp_agent_mail by @doodlestein — Inspiration for agent-to-agent messaging
• Pi coding agent by @badlogicgames

License

MIT