pi-messenger

The Team layer is an optional wrapper around Crew that adds project-local roles, a charter, durable memory, and high-risk approval gates. Active Team state is stored in .pi/messenger/team/.

Key Capabilities

• Roles: Assign specific responsibilities (e.g., scout, worker, reviewer) to agents. Built-in roles include context-builder, delegate, oracle, planner, researcher, reviewer, scout, and worker.
• Approvals: Define high-risk tasks (e.g., tagged with database or migration) that require manual approval before workers proceed.
• Memory: Store project-specific decisions and context.

API Commands

• team.setup: Activates a profile (e.g., migration-squad) and creates a charter.
• team.memory.note: Adds a durable note to the team memory.
• team.roles: Lists active roles.
• team.status: Shows current team status.

// Setup a migration squad with approval gates
pi_messenger({ action: "team.setup", name: "migration-squad" });

// Add a decision to team memory
pi_messenger({ action: "team.memory.note", type: "decision", message: "Auth API changes require reviewer sign-off." });

// Check team status
pi_messenger({ action: "team.status" });

Crew transforms a Product Requirements Document (PRD) into a dependency graph of tasks and executes them in parallel waves.

Workflow

1. Plan: The Planner explores the codebase and PRD to draft tasks with dependencies. It refines the plan until it reaches a SHIP state or the maxPasses limit. Progress is logged to .pi/messenger/crew/planning-progress.md within your project directory.
2. Work: Workers implement tasks whose dependencies are met. A single work call executes one wave. Using autonomous: true runs waves sequentially until completion or blockage. Tasks are automatically reviewed after completion; results include SHIP (done), NEEDS_WORK (retry with feedback), or MAJOR_RETHINK (blocks task).
3. Review: You can manually review a specific task or the entire plan using the review action.

Wave Execution

Tasks are organized into waves based on their dependencies. Independent tasks run concurrently in the same wave. Once a task in Wave $N$ is completed, it unblocks dependent tasks in Wave $N+1$.

// Plan and auto-start autonomous work when planning completes
pi_messenger({ action: "plan" });

// Plan with a specific prompt
pi_messenger({ action: "plan", prompt: "Scan the codebase for bugs" });

// Manual review of a specific task
pi_messenger({ action: "review", target: "task-1" });

Pi-messenger is a pi extension that hooks into the agent lifecycle using specific event listeners:

• pi.on("tool_call") and pi.on("tool_result"): Used to track activity like edits, commits, and test runs.
• pi.on("session_start"): Handles auto-registration.
• pi.on("session_shutdown"): Handles cleanup.
• pi.on("agent_end"): Drives autonomous crew mode by checking for ready tasks.

Key Mechanisms:

• Messaging: Incoming messages use pi.sendMessage() with triggerTurn: true and deliverAs: "steer" to inject messages as steering prompts.
• File Reservations: Enforced by returning { block: true } from a tool_call hook during write/edit operations.
• Crew Workers: Spawned as pi --mode json subprocesses. Progress is tracked via JSONL streaming.
• Coordination: File-based (no daemon required). Shared state lives in ~/.pi/agent/messenger/. Project-scoped activity and crew logs live in <project>/.pi/messenger/.

Crew workers can acquire domain-specific knowledge via Skills. Skills are discovered from three hierarchical locations (later sources override earlier ones):

1. User skills: ~/.pi/agent/skills/ (using dir/SKILL.md format).
2. Extension skills: crew/skills/ within the extension.
3. Project skills: .pi/messenger/crew/skills/ in your project root.

The planner indexes these skills and tags tasks with relevant ones. Workers load the full content of a skill only when needed via read(), optimizing token usage.

To add a project-level skill, create a .md file in .pi/messenger/crew/skills/ with a YAML frontmatter header containing name and description.

---
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.

Crew can consume significant tokens because it runs multiple LLM sessions in parallel. You can configure models and execution constraints in ~/.pi/agent/pi-messenger.json.

Model Configuration

By default, agents inherit the host session model. You can override models per role using the crew.models.<role> key. Model strings support the provider/model format and a :level suffix for inline thinking control (e.g., anthropic/claude-sonnet-4:high).

Configuration Reference

All fields are optional. Settings are applied in the following hierarchy: crew.models.<role> > agent frontmatter > host session model.

Default Agent Roles and Fallbacks

{
  "crew": {
    "concurrency": { "workers": 2, "max": 10 },
    "models": {
      "worker": "anthropic/claude-haiku-4-5",
      "planner": "openrouter/anthropic/claude-sonnet-4:high"
    },
    "review": { "enabled": true, "maxIterations": 3 },
    "planning": { "maxPasses": 1 },
    "work": {
      "maxAttemptsPerTask": 5,
      "maxWaves": 50
    }
  }
}

Pi Messenger enables agents to communicate across terminal sessions using file-based coordination (no daemon required).

Core Workflow:

1. Registration: An agent joins the mesh by creating registration files in a shared directory (default: ~/.pi/agent/messenger).
2. Discovery: Agents use a watcher to monitor the registry for other active agents.
3. Messaging: Messages are delivered via agent_message types. The extension handles unread counts, chat history, and identity tracking (detecting if a sender is a new session).
4. Status Tracking: The extension automatically updates the terminal status bar with peer counts, unread messages, planning progress, and active 'Crew' work (e.g., ⚡2/5 🔨1).
5. Activity Monitoring: The extension tracks agent activity (editing files, running tests, committing code) to provide a real-time status and detect if an agent has become 'stuck'.