Agents

Bosun's agents are specialized Pi instances, each with a specific role, model tier, and set of tools. They run in tmux windows and coordinate through a mesh.

Agent roster

Model tiers

Agents declare a tier, not a specific model. You map tiers to models in config.toml:

[models]
lite = "<your-fast-model>"               # e.g. gpt-4.1-mini, claude-haiku-4-5
medium = "<your-balanced-model>"          # e.g. gpt-5.3-codex, claude-sonnet-4-6
high = "<your-best-model>"               # e.g. gpt-5.4, claude-opus-4-6
oracle = "<your-reasoning-model>"         # e.g. gpt-5.4, o3

Change the model behind a tier without touching any agent definitions.

Spawning agents

From bosun (or any orchestrator), spawn agents with:

spawn_agent({
  agent: "lite",
  task: "Refactor the auth module. Send one concise mesh_send report to bosun with blockers, decisions, or completion summary."
})

This:

1. Resolves lite → finds lite.md (checks .pi/agents/ overrides first, then packages/pi-bosun/agents/)
2. Reads frontmatter: model tier, extensions, skills
3. Resolves tier → actual model from config
4. Spawns a new Pi instance in a tmux window
5. The agent auto-joins the mesh and starts working

Window vs session

By default, agents spawn in tmux windows (same session). Use session: true for agents that:

• Work on a separate repo
• Are long-lived (like Q)
• Need direct user interaction

// Window (default) — short-lived helper
spawn_agent({ agent: "lite", task: "..." })

// Session — long-lived, interactive
spawn_agent({ agent: "q", session: true, task: "..." })

Mesh coordination

All agents auto-join the mesh on spawn. The mesh provides:

Peer awareness

mesh_peers({})
// Returns: who's active, what they're working on, their status

File reservations

Before editing shared files, reserve them:

mesh_reserve({ paths: ["src/auth/"], reason: "Refactoring auth" })
// Other agents see this and avoid editing those files

Release when done:

mesh_release({})

Messaging

Agents communicate through mesh messages for coordination, not conversation:

// Send one substantive completion/blocker report to a specific agent
mesh_send({ to: "bosun", message: "Done. 42/42 tests pass. No blockers." })

// Broadcast only when other agents actually need to know
mesh_send({ broadcast: true, message: "Auth interfaces changed; rebase or re-read before editing auth." })

// Urgent (interrupts the recipient)
mesh_send({ to: "lite-1", message: "Stop — requirements changed.", urgent: true })

Prefer one concise, batched message over a stream of tiny updates. Do not send acknowledgment-only messages like ack, got it, thanks, or emoji reactions. Messages arrive as follow-up events — no polling needed.

Agent definitions

Default agents live in packages/pi-bosun/agents/*.md. Shared bosun prompt policy lives in packages/pi-bosun/slots/*.md — including mesh coordination/reporting behavior. Override any agent by placing a file with the same name in .pi/agents/. Definitions use YAML frontmatter:

---
name: lite
model: lite
description: Fast helper for quick tasks
extensions:
  - npm:pi-mesh
  - npm:pi-tmux
skills:
  - git
  - context-management
---

You are lite, a fast helper agent...

Key fields:

• model: Tier name (lite, medium, high, oracle)
• extensions: Pi packages loaded for this agent
• skills: Skills available to load on demand

Writing custom agents

Create .pi/agents/your-agent.md:

---
name: security-reviewer
model: medium
description: Security-focused code review
extensions:
  - npm:pi-mesh
---

You are a security reviewer. Focus on:
- Input validation
- Auth/authz patterns
- SQL injection, XSS
- Secrets in code
...

Then spawn it: spawn_agent({ agent: "security-reviewer", task: "..." })

Use the meta-agent-creator skill for scaffolding guidance.