Swarm Details	Swarm Messenger
Memory Channel	Session Channel

From npm:

pi install npm:pi-messenger-swarm

From git (Pi package settings):

{
  "packages": ["https://github.com/monotykamary/pi-messenger-swarm@main"]
}

Tip: after release tags are published, pin to a version tag instead of main (for example @vX.Y.Z).

Join the messenger and start collaborating in your session channel:

pi-messenger-swarm join
pi-messenger-swarm send #memory "Investigating auth timeout in refresh flow"
pi-messenger-swarm task create --title "Investigate auth timeout" --content "Repro + fix"
pi-messenger-swarm task claim task-1
pi-messenger-swarm task progress task-1 "Found race in refresh flow"
pi-messenger-swarm task done task-1 "Fixed refresh lock + tests"

Spawn a specialized subagent:

pi-messenger-swarm spawn --role "Packaging Gap Analyst" --persona "Skeptical market researcher" "Find productization gaps in idea aggregation tools"

Pi Messenger is now channel-first.

Each Pi session gets a dedicated default channel, generated as a human-friendly phrase such as:

• #quiet-river
• #wild-viper
• #ember-owl

The same Pi sessionId restores the same session channel when reopened.

By default, a durable named channel is created:

• #memory — cross-session knowledge, notes, decisions, and async handoff

You can create additional named channels as needed.

You can also create additional named channels explicitly with join.

Channel messages are durable even when nobody is listening.

Posting to a channel means:

1. append to that channel's feed
2. try live inbox delivery to agents currently joined to that channel

That makes channels useful as async coordination logs for later agents to pick up.

If Pi switches or resumes sessions inside the same live messenger instance, messenger rebinds to the resumed Pi session:

• restores the correct session channel
• drops stale old session-channel membership
• restarts watchers on the correct inbox
• keeps named channels like #memory

• join
• status
• list
• whois
• feed
• set_status
• send
• reserve
• release
• rename

• swarm — summary of tasks + spawned agents

• task.create
• task.list
• task.show
• task.ready
• task.claim (alias: task.start)
• task.unclaim (alias: task.stop)
• task.progress
• task.done
• task.block
• task.unblock
• task.reset (cascade: true supported)
• task.delete
• task.archive_done (moves completed tasks to .pi/messenger/archive/<channel>/...)

Compatibility aliases:

• claim → task.claim
• unclaim → task.unclaim
• complete → task.done

• spawn
• spawn.list
• spawn.stop

send now always requires an explicit to: target.

pi-messenger-swarm send OtherAgent "Need your API shape before I commit"

pi-messenger-swarm send #memory "Claimed task-4, touching src/auth/session.ts"
pi-messenger-swarm send #memory "Nightly sync complete"

pi-messenger-swarm join --channel memory
pi-messenger-swarm join --channel architecture --create

pi-messenger-swarm feed --limit 20
pi-messenger-swarm feed --channel memory --limit 20

• to: "#channel" is the canonical way to post to a channel
• send without to is invalid
• the old broadcast action is removed
• for channel posts, prefer to: "#channel" over channel: "..."

Run /messenger to open the swarm overlay.

Overlay includes:

• live agent presence
• swarm task list/detail
• live feed for the current channel
• DM/current-channel post input
• channel switching

Message input behavior:

• @name <message> sends a DM
• plain text posts to the current channel

Planning UI and worker +/- controls were removed in swarm mode.

By default, swarm state is project-scoped (isolated per project). All channel state uses a unified event-sourced JSONL format:

.pi/messenger/
├── channels/                    # Unified event-sourced channel files
│   ├── memory.jsonl           # Line 1: metadata header, Line 2+: feed events
│   └── quiet-river.jsonl
├── tasks/                       # Per-session task storage
│   ├── session-abc.jsonl      # Task event log (created, claimed, done, etc.)
│   └── session-abc/           # Task specs directory
│       ├── task-1.md
│       └── task-1.progress.md
├── agents/                      # Per-session spawned agent storage
│   ├── session-abc.jsonl      # Agent event log (spawned, completed, failed, stopped)
│   └── session-abc/           # Agent definition files
│       └── AgentName-id.md
├── registry/                    # Agent registrations (joined mesh agents)
│   ├── AgentA.json
│   └── AgentB.json

Each channel file at channels/<channel>.jsonl uses an append-only JSONL format:

Line 1 — Metadata header:

{
  "_meta": true,
  "v": 1,
  "id": "memory",
  "type": "named",
  "createdAt": "2026-04-04T22:00:00.000Z",
  "description": "Cross-session knowledge and insights"
}

Line 2+ — Append-only feed events:

{"ts":"2026-04-04T22:05:00.000Z","agent":"Alpha","type":"join"}
{"ts":"2026-04-04T22:10:00.000Z","agent":"Alpha","type":"message","preview":"Investigating auth timeout"}
{"ts":"2026-04-04T22:15:00.000Z","agent":"Alpha","type":"task.start","target":"task-1"}

This design provides:

• Atomic channel creation — metadata and first event written together
• Append-only feeds — events never modified, only added
• Natural event sourcing — full history preserved in file order
• Efficient tail reads — recent events at end of file
• Simple caching — stat mtime + size for invalidation

This design intentionally breaks older messaging assumptions.

• broadcast action was removed
• send without to was removed
• feed history is now stored per channel at .pi/messenger/channels/<channel>.jsonl (unified format: metadata header + events)
• tasks are now stored per session at .pi/messenger/tasks/<session>.jsonl
• session channels are phrase-based instead of session-* timestamp-like ids

Use these patterns instead:

pi-messenger-swarm send AgentName "..."
pi-messenger-swarm send #channel "..."

Override the default project-scoped behavior:

# Custom location
PI_MESSENGER_DIR=/tmp/swarm-state pi

# Legacy global mode (not recommended)
PI_MESSENGER_GLOBAL=1 pi

For backwards compatibility only - agents from ALL projects share state:

• ~/.pi/agent/messenger/registry - Agent registrations
• ~/.pi/agent/messenger/inbox - Cross-agent messaging

Legacy PRD planner/worker/reviewer actions are disabled in swarm mode:

• plan*
• work*
• review*
• crew.* (legacy alias namespace)

Use task.*, spawn.*, and swarm instead.

MIT