pi-messenger 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.10.0] - 2026-02-05
+
+### Fixed
+- **Crew spawner applies agent definitions** — Spawned crew workers now receive the agent's system prompt (`--append-system-prompt`), tool restrictions (`--tools`), and model override from their `.md` definitions. Previously a phantom `--agent` flag was passed that pi-core silently ignored, the agent name leaked into the prompt as noise, and the system prompts (worker's 6-phase protocol, reviewer's rubric, planner's exploration workflow) were never delivered. Tool restrictions also take effect: reviewers and interview generators are now limited to `read,bash` instead of getting all default builtins including `write` and `edit`.
+- **Crew spawner session cleanup** — Spawned workers now pass `--no-session` to avoid writing ephemeral session files to disk.
+
+### Added
+- **`--crew-install` / `--crew-uninstall` CLI flags** — `npx pi-messenger --crew-install` copies crew agent `.md` files and the `pi-messenger-crew` skill to user directories. `--crew-uninstall` removes them. Reads from the npm package (not the installed extension) to avoid version skew.
+
+### Changed
+- **README rewrite** — Installation section now shows real CLI commands instead of tool-call syntax. "How It Works" section explains pi extension API hooks (`pi.on()`, `pi.sendMessage()`, `{ block: true }`, `ctx.ui.custom()`) instead of listing directory trees.
+
 ## [0.9.0] - 2026-02-05
 
 ### Added

package/README.md

@@ -6,106 +6,76 @@
 
 **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. Built on [Pi's](https://github.com/badlogic/pi-mono) extension system. No daemon, no server, just files.
 
+[![npm version](https://img.shields.io/npm/v/pi-messenger?style=for-the-badge)](https://www.npmjs.com/package/pi-messenger)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
 [![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-blue?style=for-the-badge)]()
 
-> ⚠️ **Beta** - Core messaging, presence, and file reservations are stable. **Crew task orchestration** (plan/work/review) is newer and not fully tested yet. Please [open an issue](https://github.com/nicobailon/pi-messenger/issues) if you encounter problems.
-
-Pi-messenger adds a `pi_messenger` tool that **agents use** for coordination. You don't type these commands - you ask your agent to do things, and it calls `pi_messenger` behind the scenes.
-
-## Quick Start
-
-### Multi-Agent Coordination
-
-Once joined (manually or via auto-join config), agents can coordinate:
-
-```typescript
-pi_messenger({ action: "reserve", paths: ["src/auth/"], reason: "Refactoring" })
-// → Reserved src/auth/ - other agents will be blocked
-
-// ... does the work ...
+## Installation
 
-pi_messenger({ action: "release" })
-// → Released all reservations
+```bash
+pi install npm:pi-messenger
 ```
 
-> **Tip:** Set `autoRegister: true` in your config to auto-join on startup. Otherwise, agents join with `pi_messenger({ action: "join" })`.
-
-### Crew Task Orchestration
-
-Ask your agent to plan and execute from a PRD:
-
-```typescript
-pi_messenger({ action: "plan" })
-// → Planner analyzes codebase, creates tasks
+Crew agents and the `pi-messenger-crew` skill are auto-installed on first use of `plan`, `work`, or `review`. To install them ahead of time:
 
-pi_messenger({ action: "work", autonomous: true })
-// → Workers execute tasks in waves until done
+```bash
+npx pi-messenger --crew-install
 ```
 
-> **Note:** Crew agents (planner, workers, reviewers) automatically join the mesh as their first action.
+This copies `crew/agents/*.md` to `~/.pi/agent/agents/` and `skills/pi-messenger-crew/` to `~/.pi/agent/skills/`.
 
-## Installation
+To remove the extension:
 
 ```bash
-pi install npm:pi-messenger
+npx pi-messenger --remove
 ```
 
-To remove:
+To also remove crew agents and skill:
 
 ```bash
-npx pi-messenger --remove
+npx pi-messenger --crew-uninstall
 ```
 
-After joining, your agent name appears in the status bar:
+## Quick Start
+
+Once joined (manually or via `autoRegister` config), agents can coordinate:
 
+```typescript
+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" })
 ```
-msg: SwiftRaven (2 peers) ●3
+
+For multi-agent task orchestration from a PRD:
+
+```typescript
+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** - Agents have rich presence with status indicators (🟢 active, 🟡 idle, 🟠 away, 🔴 stuck), tool call counts, token usage, and auto-generated status messages like "on fire 🔥" or "debugging...".
+**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** - A unified timeline of everything happening: edits, commits, test runs, messages, task starts/completions. Crew events appear inline with a `[Crew]` prefix.
+**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. Great for handoffs and coordination.
+**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. You get a notification so you can intervene.
-
-**Human as Participant** - Your interactive pi session appears in the agent list with `(you)`. Same activity tracking, same status messages. You can chat from the overlay.
+**Stuck Detection** - Agents idle too long with an open task or reservation are flagged as stuck. Peers get a notification.
 
-**Swarm Coordination** - Multiple agents work on the same spec file. Claim tasks atomically, mark them complete, see who's doing what.
+**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:
 
-```
-╭─ Messenger ── 3 agents ── myapp ────────────────────╮
-│                                                      │
-│ 🟢 SwiftRaven (you)                                  │
-│    editing login.ts - 12 tools - 31.0k - on fire 🔥  │
-│                                                      │
-│ 🟡 GoldFalcon                             idle 2m    │
-│    8 tools - 24.1k - 📁 src/api/                     │
-│                                                      │
-│ 🔴 IronKnight                             stuck      │
-│    3 tools - 16.4k                                   │
-│                                                      │
-│ Activity                                             │
-│ 10:42 SwiftRaven editing login.ts                    │
-│ 10:40 GoldFalcon → SwiftRaven: "auth done?"          │
-│ 10:38 SwiftRaven committed "feat: add OAuth"         │
-│ 10:35 [Crew] GoldFalcon started task-03              │
-├──────────────────────────────────────────────────────┤
-│ > @GoldFalcon almost done                [Tab] [Enter]│
-╰──────────────────────────────────────────────────────╯
-```
+<img width="722" height="351" alt="pi-messenger chat overlay" src="https://github.com/user-attachments/assets/4d0f1db7-90dd-4ffb-9463-560426edebd9" />
 
 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.
 
@@ -118,120 +88,19 @@ Chat input supports `@Name msg` for DMs and `@all msg` for broadcasts. Text with
 
 ## Crew: Task Orchestration
 
-Crew provides multi-agent task orchestration with a simplified PRD-based workflow.
+Crew turns a PRD into a dependency graph of tasks, then executes them in parallel waves.
 
-### Basic Workflow
+### Workflow
 
-1. **Plan** - Planner analyzes your codebase and PRD, creates tasks
-2. **Work** - Workers implement tasks in parallel waves
-3. **Review** - Reviewer checks each implementation
-
-```typescript
-// Plan from your PRD (auto-discovers PRD.md, SPEC.md, etc.)
-pi_messenger({ action: "plan" })
-
-// Or specify PRD path explicitly
-pi_messenger({ action: "plan", prd: "docs/PRD.md" })
-
-// Execute tasks (spawns parallel workers)
-pi_messenger({ action: "work" })
-
-// Or run autonomously until done/blocked
-pi_messenger({ action: "work", autonomous: true })
-
-// Review a specific task
-pi_messenger({ action: "review", target: "task-1" })
-// → SHIP ✅ or NEEDS_WORK 🔄
-```
-
-### Crew API
-
-**Planning**
-| Action | Description | Example |
-|--------|-------------|---------|
-| `plan` | Create plan from PRD | `{ action: "plan" }` or `{ action: "plan", prd: "..." }` |
-| `status` | Show progress | `{ action: "status" }` |
-
-**Work Execution**
-| Action | Description | Example |
-|--------|-------------|---------|
-| `work` | Run ready tasks | `{ action: "work" }` |
-| `work` (auto) | Run until done/blocked | `{ action: "work", autonomous: true }` |
-
-**Task Management**
-| Action | Description | Example |
-|--------|-------------|---------|
-| `task.show` | Show task details | `{ action: "task.show", id: "task-1" }` |
-| `task.list` | List all tasks | `{ action: "task.list" }` |
-| `task.start` | Start task | `{ action: "task.start", id: "task-1" }` |
-| `task.done` | Complete task | `{ action: "task.done", id: "task-1", summary: "..." }` |
-| `task.block` | Block task | `{ action: "task.block", id: "task-1", reason: "..." }` |
-| `task.unblock` | Unblock task | `{ action: "task.unblock", id: "task-1" }` |
-| `task.ready` | List ready tasks | `{ action: "task.ready" }` |
-| `task.reset` | Reset task | `{ action: "task.reset", id: "task-1", cascade: true }` |
-
-**Review**
-| Action | Description | Example |
-|--------|-------------|---------|
-| `review` | Review implementation | `{ action: "review", target: "task-1" }` |
-
-**Maintenance**
-| Action | Description | Example |
-|--------|-------------|---------|
-| `crew.status` | Overall status | `{ action: "crew.status" }` |
-| `crew.validate` | Validate plan | `{ action: "crew.validate" }` |
-| `crew.agents` | List crew agents | `{ action: "crew.agents" }` |
-| `crew.install` | Install crew agents | `{ action: "crew.install" }` |
-
-### Planning Workflow
-
-The `plan` action runs a multi-pass planning loop: the planner drafts tasks, a reviewer checks them against the PRD, and the planner refines until SHIP or `planning.maxPasses` is reached. All passes and feedback are stored in `.pi/messenger/crew/planning-progress.md`.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  Your Project                                                    │
-│  ├── PRD.md            ◄── Planner discovers and reads these    │
-│  ├── DESIGN.md                                                   │
-│  ├── src/                                                        │
-│  └── ...                                                         │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  Planner (opus)                                                  │
-│  ├── Explores codebase structure and patterns                    │
-│  ├── Reads project documentation                                 │
-│  ├── Identifies gaps, edge cases, security concerns              │
-│  └── Drafts task breakdown with dependencies                     │
-└─────────────────────────────────────────────────────────────────┘
-                              │ append to
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  planning-progress.md (history + feedback)                       │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  Reviewer (gpt-5.2-high)                                          │
-│  ├── SHIP  ✅  or NEEDS_WORK 🔄                                  │
-│  └── Feeds back into the next planner pass                       │
-└─────────────────────────────────────────────────────────────────┘
-                              │ SHIP
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  Result: Tasks with Dependencies                                 │
-│  ├── task-1: Setup types        (no deps)                       │
-│  ├── task-2: Core logic         (depends on task-1)             │
-│  ├── task-3: API endpoints      (depends on task-1)             │
-│  └── task-4: Tests              (depends on task-2, task-3)     │
-└─────────────────────────────────────────────────────────────────┘
-```
+1. **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`.
+2. **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.
+3. **Review** — Reviewer checks each implementation: SHIP, NEEDS_WORK, or MAJOR_RETHINK.
 
-**No special format required** -- just put your docs in the project. The planner finds and reads markdown files, READMEs, and code comments.
+No special PRD format required — the planner auto-discovers `PRD.md`, `SPEC.md`, `DESIGN.md`, etc. in your project root and `docs/`.
 
-### How Work Execution Works
+### Wave Execution
 
-Crew doesn't run tasks sequentially. Tasks form a dependency graph, and the work handler executes them in **waves** based on what's ready:
+Tasks form a dependency graph. Independent tasks run concurrently:
 
 ```
 Wave 1:  task-1 (no deps)  ─┐
@@ -243,63 +112,7 @@ Wave 2:  task-2 (→ task-1) ─┤── task-1 done, task-2 unblocked
 Wave 3:  task-5 (→ task-2, task-4) ── both deps done
 ```
 
-A task is **ready** when its status is pending and all its dependencies are completed. Each wave picks all ready tasks (up to `concurrency.workers`), spawns parallel workers, waits for them to finish, then checks what's newly unblocked. Independent tasks — those that don't depend on each other — run concurrently in the same wave.
-
-The planner structures tasks to maximize this parallelism. Foundation work (types, config, schemas) has no dependencies so it starts immediately. Features that don't touch each other get separate dependency chains so they can run in parallel. Tasks that need shared work done first (tests, integration, docs) depend on the tasks that produce it.
-
-A single `work` call runs one wave. Autonomous mode (`autonomous: true`) runs waves back-to-back until everything is done or blocked.
-
-### Autonomous Mode
-
-Run tasks continuously until completion:
-
-```typescript
-pi_messenger({ action: "work", autonomous: true })
-```
-
-Autonomous mode:
-- Executes waves of parallel workers
-- Auto-blocks on failure
-- Stops when all tasks done or blocked
-- Respects `maxWaves` limit (default: 50)
-
-### Crew Overlay Tab
-
-The `/messenger` overlay includes a Crew tab showing task status:
-
-```
-╭─ Messenger ── 3 agents ── myapp ──────────────────────╮
-│ Agents │ ▸ Crew (2/5) │ ● GoldFalcon │ + All         │
-├──────────────────────────────────────────────────────┤
-│                                                      │
-│  📋 docs/PRD.md                              [2/5]   │
-│                                                      │
-│  ✓ task-1  Setup OAuth config                        │
-│  ✓ task-2  Implement token storage                   │
-│  ● task-3  Add Google provider (SwiftRaven)          │
-│  ○ task-4  Add GitHub provider → task-2              │
-│  ○ task-5  Write tests → task-3, task-4              │
-│                                                      │
-├──────────────────────────────────────────────────────┤
-│ ● AUTO Wave 2 │ 2/5 done │ 1 ready │ ⏱️ 3:42        │
-╰──────────────────────────────────────────────────────╯
-```
-
-### Crew Data Storage
-
-```
-.pi/messenger/crew/
-├── plan.json               # Plan metadata (PRD path, progress)
-├── plan.md                 # Planner output
-├── planning-progress.md    # Planning loop history + feedback
-├── tasks/
-│   ├── task-1.json         # Task metadata
-│   ├── task-1.md           # Task specification
-│   └── ...
-├── blocks/                 # Block context for blocked tasks
-├── artifacts/              # Debug artifacts
-└── config.json             # Project-level crew config
-```
+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 Configuration
 
@@ -316,121 +129,55 @@ Add to `~/.pi/agent/pi-messenger.json`:
 }
 ```
 
-| Setting | Description | Default |
-|---------|-------------|---------|
-| `concurrency.workers` | Max parallel workers during work | `2` |
-| `review.enabled` | Enable review functionality | `true` |
-| `review.maxIterations` | Max review iterations per task | `3` |
-| `planning.maxPasses` | Max planner passes before accepting last output | `3` |
-| `work.maxAttemptsPerTask` | Retries before blocking a task | `5` |
-| `work.maxWaves` | Max waves in autonomous mode | `50` |
-
-### Crew Install
+Crew agents (planner, worker, reviewer, interview-generator, plan-sync) are **auto-installed** on first use. Run `npx pi-messenger --crew-install` to manually install or update.
 
-Crew agents are **auto-installed** on first use of `plan`, `work`, or `review`. To manually install or update:
+## API Reference
 
-```typescript
-pi_messenger({ action: "crew.install" })
-```
+### Coordination
 
-**What gets installed:**
-- **5 agents** in `~/.pi/agent/agents/` (planner, worker, reviewer, interview-generator, plan-sync)
-- **1 skill** in `~/.pi/agent/skills/` (pi-messenger-crew quick reference)
-
-To remove:
-```typescript
-pi_messenger({ action: "crew.uninstall" })
-```
-
-## Tool Reference
-
-### Action-Based API (Recommended)
-
-**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 |
-| `feed` | Show activity feed |
-| `set_status` | Set custom status message (omit `message` to clear) |
-| `send` | Send DM (requires `to` + `message`) |
-| `broadcast` | Broadcast to all (requires `message`) |
-| `reserve` | Reserve files (requires `paths`) |
-| `release` | Release reservations (optional `paths`, or releases all) |
-| `rename` | Change your name (requires `name`) |
-| `swarm` | Show swarm task status |
-| `claim` | Claim a swarm task (requires `taskId`) |
-| `unclaim` | Release a swarm claim (requires `taskId`) |
-| `complete` | Complete a swarm task (requires `taskId`) |
+| `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) |
 
-```typescript
-pi_messenger({
-  action: string,              // Action to perform
-
-  // Coordination
-  name?: string,               // For whois, rename
-  message?: string,            // For send, broadcast, set_status
-  to?: string | string[],      // For send
-  paths?: string[],            // For reserve, release
-  reason?: string,             // For reserve, claim, task.block
-  limit?: number,              // For feed (default: 20)
-
-  // Plan
-  prd?: string,                // PRD file path
-
-  // Task identifiers
-  id?: string,                 // Task ID (task-N)
-  taskId?: string,             // Swarm task ID
-  target?: string,             // Target for review
-
-  // Creation
-  title?: string,              // For task.create
-  dependsOn?: string[],        // Task dependencies
-
-  // Completion
-  summary?: string,            // For task.done
-
-  // Work options
-  autonomous?: boolean,        // Run continuously
-  concurrency?: number,        // Override concurrency
-
-  // Reset
-  cascade?: boolean,           // Reset dependent tasks too
-})
-```
+### Crew
 
-### Legacy API
+| Action | Description |
+|--------|-------------|
+| `plan` | Create plan from PRD (`prd` optional — auto-discovers if omitted) |
+| `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` | Install/update crew agents |
+| `crew.uninstall` | Remove crew agents and skill |
+
+### Swarm (Spec-Based)
 
-```typescript
-pi_messenger({
-  // Join
-  join?: boolean,              // Join the agent mesh
-  spec?: string,               // Spec file to work on
-
-  // Swarm
-  swarm?: boolean,             // Get swarm status
-  claim?: string,              // Claim a task
-  unclaim?: string,            // Release without completing
-  complete?: string,           // Mark task complete
-  notes?: string,              // Completion notes
-
-  // Messaging
-  to?: string | string[],      // Recipient(s)
-  broadcast?: boolean,         // Send to all
-  message?: string,            // Message text
-
-  // Reservations
-  reserve?: string[],          // Paths to reserve
-  reason?: string,             // Why reserving/claiming
-  release?: string[] | true,   // Release reservations
-
-  // Other
-  rename?: string,             // Change your name
-  list?: boolean,              // List active agents
-})
-```
+| 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
 
@@ -452,32 +199,30 @@ Create `~/.pi/agent/pi-messenger.json`:
 | `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 generation theme: `default`, `nature`, `space`, `minimal`, `custom` | `"default"` |
+| `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` (15m) |
+| `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` |
 | `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/agent/messenger/
-├── registry/           # Agent registrations (PID, cwd, model, activity, tokens)
-├── inbox/              # Message delivery
-├── feed.jsonl          # Activity feed (append-only, pruned on startup)
-├── claims.json         # Active task claims
-├── completions.json    # Completed tasks
-└── swarm.lock          # Atomic lock for claims
-```
+Pi-messenger is a [pi extension](https://github.com/badlogic/pi-mono) 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 planner and reviewer work the same way — just pi instances with different agent configs.
 
-File-based coordination. No daemon. Activity tracking updates the registry every 10 seconds via debounced flushes. Dead agents detected via PID and cleaned up automatically - a "leave" event is logged when stale registrations are removed.
+All coordination is file-based, no daemon required. Global state (registry, inboxes, activity feed) lives in `~/.pi/agent/messenger/`. Per-project crew data (plan, tasks, artifacts) lives in `.pi/messenger/crew/` inside your project. Dead agents are detected via PID checks and cleaned up automatically.
 
 ## Credits
 
-- **[mcp_agent_mail](https://github.com/Dicklesworthstone/mcp_agent_mail)** by [@doodlestein](https://x.com/doodlestein) - Inspiration for agent-to-agent messaging
+- **[mcp_agent_mail](https://github.com/Dicklesworthstone/mcp_agent_mail)** by [@doodlestein](https://x.com/doodlestein) — Inspiration for agent-to-agent messaging
 - **[Pi coding agent](https://github.com/badlogic/pi-mono/)** by [@badlogicgames](https://x.com/badlogicgames)
 
 ## License

package/crew/agents.ts

@@ -6,6 +6,8 @@
 
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { discoverCrewAgents, type CrewAgentConfig } from "./utils/discover.js";
@@ -31,6 +33,7 @@ import type { AgentTask, AgentResult } from "./types.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const EXTENSION_DIR = path.resolve(__dirname, "..");
+const BUILTIN_TOOLS = new Set(["read", "bash", "edit", "write", "grep", "find", "ls"]);
 
 export interface SpawnOptions {
   onProgress?: (results: AgentResult[]) => void;
@@ -113,12 +116,41 @@ async function runAgent(
 
   return new Promise((resolve) => {
     // Build args for pi command
-    const args = ["--mode", "json", "--agent", task.agent, "-p", task.task];
+    const args = ["--mode", "json", "--no-session", "-p"];
     if (agentConfig?.model) args.push("--model", agentConfig.model);
-    
+
+    if (agentConfig?.tools?.length) {
+      const builtinTools: string[] = [];
+      const extensionPaths: string[] = [];
+      for (const tool of agentConfig.tools) {
+        if (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")) {
+          extensionPaths.push(tool);
+        } else if (BUILTIN_TOOLS.has(tool)) {
+          builtinTools.push(tool);
+        }
+      }
+
+      if (builtinTools.length > 0) {
+        args.push("--tools", builtinTools.join(","));
+      }
+      for (const extensionPath of extensionPaths) {
+        args.push("--extension", extensionPath);
+      }
+    }
+
     // Pass extension so workers can use pi_messenger
     args.push("--extension", EXTENSION_DIR);
 
+    let promptTmpDir: string | null = null;
+    if (agentConfig?.systemPrompt) {
+      promptTmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-messenger-agent-"));
+      const promptPath = path.join(promptTmpDir, `${task.agent.replace(/[^\w.-]/g, "_")}.md`);
+      fs.writeFileSync(promptPath, agentConfig.systemPrompt, { mode: 0o600 });
+      args.push("--append-system-prompt", promptPath);
+    }
+
+    args.push(task.task);
+
     const proc = spawn("pi", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
 
     let jsonlBuffer = "";
@@ -166,6 +198,10 @@ async function runAgent(
         });
       }
 
+      if (promptTmpDir) {
+        try { fs.rmSync(promptTmpDir, { recursive: true, force: true }); } catch {}
+      }
+
       resolve({
         agent: task.agent,
         exitCode: code ?? 1,
@@ -194,4 +230,3 @@ async function runAgent(
     }
   });
 }
-

package/install.mjs

@@ -7,8 +7,10 @@
  * No git dependency — the npm package IS the source.
  *
  * Usage:
- *   npx pi-messenger          # Install or update
- *   npx pi-messenger --remove # Remove the extension
+ *   npx pi-messenger                # Install or update extension
+ *   npx pi-messenger --remove       # Remove the extension
+ *   npx pi-messenger --crew-install   # Install crew agents and skills
+ *   npx pi-messenger --crew-uninstall # Remove crew agents and skills
  */
 
 import * as fs from "node:fs";
@@ -19,12 +21,35 @@ import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
 const PACKAGE_DIR = path.dirname(__filename);
 const EXTENSION_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", "pi-messenger");
+const AGENTS_DIR = path.join(os.homedir(), ".pi", "agent", "agents");
+const SKILLS_DIR = path.join(os.homedir(), ".pi", "agent", "skills");
+
+const CREW_AGENTS = [
+	"crew-planner.md",
+	"crew-interview-generator.md",
+	"crew-plan-sync.md",
+	"crew-worker.md",
+	"crew-reviewer.md",
+];
+
+const DEPRECATED_AGENTS = [
+	"crew-repo-scout.md",
+	"crew-practice-scout.md",
+	"crew-docs-scout.md",
+	"crew-web-scout.md",
+	"crew-github-scout.md",
+	"crew-gap-analyst.md",
+];
+
+const CREW_SKILLS = ["pi-messenger-crew"];
 
 const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_DIR, "package.json"), "utf-8"));
 const VERSION = pkg.version;
 
 const args = process.argv.slice(2);
 const isRemove = args.includes("--remove") || args.includes("-r");
+const isCrewInstall = args.includes("--crew-install");
+const isCrewUninstall = args.includes("--crew-uninstall");
 const isHelp = args.includes("--help") || args.includes("-h");
 
 if (isHelp) {
@@ -32,15 +57,103 @@ if (isHelp) {
 pi-messenger v${VERSION} - Multi-agent coordination for pi
 
 Usage:
-  npx pi-messenger          Install or update
-  npx pi-messenger --remove Remove the extension
-  npx pi-messenger --help   Show this help
-
-Installation directory: ${EXTENSION_DIR}
+  npx pi-messenger                Install or update extension
+  npx pi-messenger --remove       Remove the extension
+  npx pi-messenger --crew-install   Install crew agents and skills
+  npx pi-messenger --crew-uninstall Remove crew agents and skills
+  npx pi-messenger --help          Show this help
+
+Extension directory: ${EXTENSION_DIR}
+Agents directory:    ${AGENTS_DIR}
+Skills directory:    ${SKILLS_DIR}
 `);
 	process.exit(0);
 }
 
+// ─── Crew install ────────────────────────────────────────────────────────────
+
+if (isCrewInstall) {
+	const sourceAgents = path.join(PACKAGE_DIR, "crew", "agents");
+	if (!fs.existsSync(sourceAgents)) {
+		console.error("Could not find crew agent files in package.");
+		process.exit(1);
+	}
+
+	fs.mkdirSync(AGENTS_DIR, { recursive: true });
+	fs.mkdirSync(SKILLS_DIR, { recursive: true });
+
+	let installed = 0;
+	let updated = 0;
+
+	for (const agent of DEPRECATED_AGENTS) {
+		const target = path.join(AGENTS_DIR, agent);
+		if (fs.existsSync(target)) {
+			fs.unlinkSync(target);
+		}
+	}
+
+	for (const agent of CREW_AGENTS) {
+		const src = path.join(sourceAgents, agent);
+		const dst = path.join(AGENTS_DIR, agent);
+		if (!fs.existsSync(src)) continue;
+		const existed = fs.existsSync(dst);
+		fs.copyFileSync(src, dst);
+		if (existed) updated++;
+		else installed++;
+	}
+
+	const sourceSkills = path.join(PACKAGE_DIR, "skills");
+	for (const skill of CREW_SKILLS) {
+		const srcDir = path.join(sourceSkills, skill);
+		const dstDir = path.join(SKILLS_DIR, skill);
+		if (!fs.existsSync(srcDir)) continue;
+		const existed = fs.existsSync(dstDir);
+		fs.mkdirSync(dstDir, { recursive: true });
+		for (const file of fs.readdirSync(srcDir)) {
+			const srcFile = path.join(srcDir, file);
+			if (fs.statSync(srcFile).isFile()) {
+				fs.copyFileSync(srcFile, path.join(dstDir, file));
+			}
+		}
+		if (existed) updated++;
+		else installed++;
+	}
+
+	console.log(`Crew installed (${installed} new, ${updated} updated)`);
+	console.log(`  Agents: ${AGENTS_DIR}`);
+	console.log(`  Skills: ${SKILLS_DIR}`);
+	process.exit(0);
+}
+
+// ─── Crew uninstall ──────────────────────────────────────────────────────────
+
+if (isCrewUninstall) {
+	let removed = 0;
+
+	for (const agent of [...CREW_AGENTS, ...DEPRECATED_AGENTS]) {
+		const target = path.join(AGENTS_DIR, agent);
+		if (fs.existsSync(target)) {
+			fs.unlinkSync(target);
+			removed++;
+		}
+	}
+
+	for (const skill of CREW_SKILLS) {
+		const target = path.join(SKILLS_DIR, skill);
+		if (fs.existsSync(target)) {
+			fs.rmSync(target, { recursive: true });
+			removed++;
+		}
+	}
+
+	console.log(removed > 0
+		? `Removed ${removed} crew file(s) from ${AGENTS_DIR} and ${SKILLS_DIR}`
+		: "Nothing to remove");
+	process.exit(0);
+}
+
+// ─── Extension remove ────────────────────────────────────────────────────────
+
 if (isRemove) {
 	if (fs.existsSync(EXTENSION_DIR)) {
 		fs.rmSync(EXTENSION_DIR, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-messenger",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Inter-agent messaging and file reservation system for pi coding agent",
   "type": "module",
   "author": "Nico Bailon",