Pi Messenger

Pi Messenger is an open-source extension for the Pi coding agent that lets multiple AI agents running in different terminals coordinate as if they were in a shared chat room. Agents join a mesh, claim memorable themed names, send direct messages or broadcasts, reserve files to prevent collisions, and track each other in a unified activity feed. The README credits mcp_agent_mail by @doodlestein as the inspiration for its agent-to-agent messaging model. Everything runs on plain files — no daemon, no server.

What It Is

Pi Messenger adds a coordination layer on top of Pi coding agent sessions. Once agents join, they appear in a shared presence list showing status, current model, and git branch. The /messenger command opens an interactive terminal overlay with tab-based navigation across agent presence, the activity feed, crew tasks, and per-agent chat threads. Chat input supports @Name for direct messages and @all for broadcasts. The README notes that your own interactive pi session shows up in the agent list marked (you), so a human participates on the same footing as the agents.

File-Based Architecture

The entire coordination system runs without any background process. Shared state — the registry, inboxes, and swarm claims — lives in ~/.pi/agent/messenger/. Project-scoped data such as the activity feed and crew logs lives under .pi/messenger/ inside each project directory. Dead agents are detected via PID checks and cleaned up automatically. Incoming messages wake the receiving agent through pi.sendMessage() with triggerTurn: true and deliverAs: "steer", injecting the message as a steering prompt. File reservations are enforced by returning { block: true } from a tool_call hook on write and edit operations.

Crew: Parallel Task Orchestration

The Crew system converts a PRD or an inline prompt into a dependency graph of tasks and executes them in parallel waves. The documented workflow has three phases. In Plan, a planner agent explores the codebase and PRD and drafts tasks with dependencies while a reviewer refines the plan until it passes or hits maxPasses. In Work, workers implement ready tasks concurrently, with autonomous: true running waves back-to-back until everything is done or blocked; each completed task gets an automatic reviewer pass. In Review, a manual or automatic check returns SHIP, NEEDS_WORK, or MAJOR_RETHINK with feedback.

Crew workers are spawned as pi --mode json subprocesses carrying their own system prompt, model, and tool restrictions. The overlay shows each worker's current tool, call count, and token usage in real time via JSONL streaming. No special PRD format is required — the planner auto-discovers PRD.md, SPEC.md, DESIGN.md, and similar files in the project root and docs/.

Crew Skills

Crew Skills let workers acquire domain knowledge on demand rather than carrying it in every prompt. Skills are discovered from three locations that override each other by name: user skills in ~/.pi/agent/skills/, extension skills bundled in crew/skills/, and project skills in .pi/messenger/crew/skills/. The planner sees a compact index of everything discovered and can tag tasks with relevant skills; workers see tagged skills as recommended alongside the full catalog and load only what they need. The README states that zero tokens are spent until a worker actually needs the knowledge.

Configuration and Model Control

Crew configuration lives in ~/.pi/agent/pi-messenger.json and supports per-role model overrides, concurrency limits and a hard ceiling of ten workers, review settings, dependency scheduling mode, and coordination verbosity levels of none, minimal, moderate, or chatty. Model strings accept provider/model format for explicit provider selection and a :level suffix for inline thinking control. Per the documented defaults, the planner and reviewer run on anthropic/claude-opus-4-6 while workers and the plan-sync analyst run on anthropic/claude-haiku-4-5. The README warns that Crew spawns multiple LLM sessions in parallel and can burn tokens quickly, recommending a cheap worker model to start.

Update: v0.15.0 and the Team Layer

The latest release is v0.15.0, published July 30, 2026. Its release notes describe an optional Team layer adding reusable profiles, a project charter and memory, role-aware tasks, approval gates, worker context, and overlay signals, along with a team.setup action for first-run configuration and task.revise guidance for rejected approval-gated tasks. The notes also state that Team roles and sample profiles were aligned with the packaged pi-subagents role vocabulary while Crew remains the execution engine, and that activity-feed reads were rewritten to scan only a bounded tail of feed.jsonl. The repository shows 659 stars and 50 forks as of early August 2026. The project is written almost entirely in TypeScript, licensed MIT, and distributed on npm as pi-messenger.