pi-messenger: letting several coding agents talk to each other over shared files

A chat room made of files

pi-messenger is a multi-agent communication extension for the pi coding agent, and its pitch is a question. What if multiple agents in different terminals sharing a folder could talk to each other like they are in a chat room? Join, see who is online and what they are doing, claim tasks, reserve files, send messages.

The answer to how it works is in one line: no daemon, no server, just files. The extension is installed into pi, the agents coordinate through the shared working directory, and the state lives there.

That design choice is the whole character of the project. There is nothing to deploy, nothing to keep alive, and nothing to configure with a connection string. Two agents in two terminals pointed at the same folder see each other. The cost is that everything depends on that folder being shared in a way that lets each agent observe the others' writes promptly, and the whole coordination protocol is built on top of file state rather than on messages over a socket.

The package is on npm as pi-messenger, the licence is MIT, the primary language is TypeScript, the default branch is main, and the last push was on 2026-08-27 with version 0.15.2 published the same day, after 0.15.1 on 2026-08-23 and 0.15.0 on 2026-07-30. The platform badge says macOS and Linux.

The repository layout is a set of small modules rather than a directory tree of features. There is an index.ts as the entry point, a store.ts for the shared state, handlers.ts, feed.ts and lib.ts, and then a cluster of overlay files for the chat interface, along with config.ts, config-overlay.ts, an install.mjs, a crew/ directory and a skills/ directory.

Installing it, and the four actions you actually use

Installation is a single command that installs the extension into pi:

pi install npm:pi-messenger

The crew agents ship with the extension, in a crew/agents/ directory, and they are discovered automatically, and the pi-messenger-crew skill is auto-loaded from the extension. Workers can load domain specific crew skills on demand while they execute a task.

There are a few npx commands for management. To show the available crew agents:

npx pi-messenger --crew-install

To remove the extension:

npx pi-messenger --remove

And to clear out stale crew agent copies left in a shared legacy directory:

npx pi-messenger --crew-uninstall

To customise an agent for one project, you copy it into a messenger directory under the project and edit it.

Once joined, whether manually or through an autoRegister configuration, the coordination actions are these:

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" })
pi_messenger({ action: "leave" })

Join, reserve, send, release, leave. That is the entire protocol surface, and it is deliberately small enough to read in one screen.

Presence, reservations and stuck detection

The features are grouped around one idea, which is that the agents should be able to coordinate the way people in a room would.

Living Presence gives status indicators of active, idle, away and stuck, along with tool call counts and token usage, and auto-generated status messages such as on fire or debugging. Your agent name appears in the status bar with the peer count, in the form msg: SwiftRaven (2 peers) ●3.

The Activity Feed is a unified timeline of edits, commits, test runs, messages and task events, and you query it with a feed action. The Discovery feature is how agents get identity, registering with memorable themed names like SwiftRaven, LunarDust and OakTree, so you can see who is active, what they are working on, and which model and git branch they are on.

File Reservations are the part that prevents real damage. You claim files or directories, and other agents get blocked with a clear message telling them who to coordinate with. Reservations auto-release on leave or on exit, so an agent that dies does not hold a lock forever.

Stuck Detection closes the loop. Agents that idle too long with an open task or an open reservation are flagged as stuck, and peers get a notification. That is a genuinely useful piece of automation, because the failure mode of a multi-agent setup is an agent that stops without saying so.

There is also a Human as Participant feature. Your interactive pi session appears in the agent list marked with (you), with the same activity tracking and the same status messages, and you can chat from the overlay.

The overlay, and the tabs you can switch between

The chat interface is a slash command. Typing /messenger opens an interactive overlay with agent presence, the activity feed and chat.

The chat input supports a name prefix for direct messages and a broadcast form for everyone, and text without a name broadcasts from the Agents tab or sends a direct message to the selected agent tab.

The key bindings are a small table:

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

So the overlay is tabbed rather than a single view. The Agents tab is where presence lives, the Crew tab is where task state lives, and the direct message tabs are per agent. The tab structure is what makes it usable with a large crew, since you are not scrolling one long transcript of everything happening.

The overlay is implemented as a set of separate modules in the repository, with overlay.ts, overlay-render.ts, overlay-actions.ts and overlay-coordinator.ts, and there is a config-overlay.ts alongside the main config.ts, so the overlay can be configured separately from the extension itself.

Crew: a PRD turned into a dependency graph

The Crew mode is the part that goes beyond coordination into orchestration. Crew turns a PRD into a dependency graph of tasks, then executes them in parallel waves.

The three actions are plan, work and review:

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

The workflow has three stages. Plan is where the planner explores the codebase and the PRD and drafts tasks with dependencies, and a reviewer checks the plan, and the planner refines it until it reaches SHIP or the maxPasses limit, with the history stored in planning-progress.md. Work is where workers implement the ready tasks, meaning the ones whose dependencies are met, in parallel waves, and a single work call runs one wave while autonomous runs waves back to back until everything is done or blocked. Review is a manual pass on a specific task or on the plan, which returns SHIP, NEEDS_WORK or MAJOR_RETHINK with detailed feedback.

The reviewer verdicts are worth understanding because they drive the loop. Each completed task gets an automatic reviewer pass, where SHIP keeps it done, NEEDS_WORK resets it for a retry with feedback, and MAJOR_RETHINK blocks it. The behaviour is controlled by review.enabled and review.maxIterations.

You do not need a document in a particular format. The planner auto-discovers PRD.md, SPEC.md, DESIGN.md and similar files in your project root and in a docs/ directory, or you can skip the file entirely with a prompt argument.

The logs are per project, under that project's working directory, in a messenger directory under a crew subdirectory, so the planning progress for a given project lives with the project.

Waves, and skills loaded on demand

The wave diagram in the README is the clearest statement of how parallelism works, because tasks form a dependency graph and independent tasks run concurrently.

The planner structures tasks to maximise parallelism. Foundation work has no dependencies and starts immediately, features that do not touch each other get separate chains, and autonomous mode stops when all tasks are done or blocked.

The risk in that design is the obvious one. Autonomous mode runs waves back to back with no further instruction, and each wave is a set of workers editing the same repository at the same time. The file reservation mechanism is what keeps that from becoming a mess, but a reservation covers the paths an agent declares, and two workers in a wave that touch adjacent files will still be editing at once.

Crew skills are the second idea. Workers follow the same join, read, implement, commit and release protocol regardless of the task, and what changes between tasks is domain knowledge, so the skills let workers acquire that knowledge on demand.

The discovery order is explicit, with later sources overriding earlier ones by name. User skills come from the standard agent skills directory, extension skills from a crew subdirectory inside the extension as flat markdown files, and project skills from a messenger directory in the project root, also as flat files.

The token economics of that are the point. The planner sees a compact index of all discovered skills and can tag tasks with the relevant ones. Workers see tagged skills as recommended for this task, with the full catalog under also available, and they load what they need by reading the file. Nothing is spent until a worker actually needs the knowledge.

Where pi-messenger is the wrong choice

The first wrong case is a single agent. If you run one pi session at a time, presence, messaging, reservations and the feed are all overhead, and the file state is a cost for no benefit. The extension is built for the case of several agents in several terminals, which is a specific way of working and not a general one.

The second is a project where agents must not edit concurrently at all. The tool makes parallel work possible, it does not make it safe, and a project that depends on a single serialised line of work is better served by one agent and a queue.

The third is anyone uneasy about the autonomous mode. The work action with autonomous set to true runs waves back to back until everything is done or blocked, with workers committing, and there is no approval step between waves. That is a powerful thing to switch on for a codebase you care about, and the review loop is a quality gate rather than a safety gate.

The fourth is a team on Windows. The platform badge covers macOS and Linux, and the package is a Node extension with a terminal overlay, so the interaction model is a Unix-shaped one.

The alternative worth weighing is the file-based coordination you would write yourself, which for two agents is a lock file and a note in a shared directory, and for a dozen agents is a queue. The value of pi-messenger is that it has the protocol already, that it exposes presence and stuck detection, and that the Crew mode turns a document into a parallel plan, and the cost is a dependency on a pre-1.0 extension that owns your agents' coordination.

Editorial conclusion

Adopt pi-messenger if you routinely run several pi agents over the same project and they keep colliding on the same files, since the file reservation mechanism turns a race into a message naming the agent to coordinate with. Keep away if you run one agent at a time, because the whole value is in the multi-agent case, and be careful with the Crew orchestration mode, since it starts workers in parallel waves and commits without asking. Before you use it, read the wave execution section to understand what runs concurrently, and note the release cadence with 0.15.2 published on 2026-08-27 and the last push the same day.

Frequently asked questions

Official sources

1. Issues
2. nicobailon/pi-messenger on GitHub
3. README
4. Releases