🤖 pi-agents

Give Pi durable, named agents. Delegate a job, keep working while the agent runs, and get its result back as a message. Watch any agent live, talk to it, or stop it. Agents survive crashes and restarts.

Agents run inside your Pi process on pi-durable, which checkpoints every step. When you resume a session, interrupted agents continue where they stopped.

[!CAUTION] Agents can't use MCP servers (earendil-works/pi#10837) or tools from other extensions, such as web search (earendil-works/pi#10386). They work with Pi's built-in tools: read, bash, edit, write, grep, find, ls, and codemode. MCP servers and extension tools live in Pi's session, while agents run on pi-durable.

Delegate work to agents and graphs Run parallel reviews, follow progress, and bring the findings together.	Agents message each other Coordinate a fix between agents, then browse their conversation.

🚀 Installation

pi install npm:pi-agents

✨ Usage

Have an agent review src/run for error handling while we keep going.

Spawn two agents in parallel: one maps the API surface, one checks the tests.
Merge their findings once both report back.

Start a graph: three agents review src/run, src/ui, and src/host, and a
fourth merges their findings into one list of issues.

Start an agent that may delegate: it finds every module under src, has one
helper review each, and returns one merged review.

Pi starts agents only when you ask for delegation. An agent's result is its final message. Agents work in the background and their results arrive as messages in your conversation, so you can keep talking to Pi meanwhile. In a graph, agents pass their results to each other, and Pi gets one message at the end.

The usage manual covers the rest: the panel, attaching to agents, graphs, delegation, messaging, profiles, and configuration.

🏗️ Architecture

Agents run inside your Pi process. Pi-agents keeps one pi-durable harness per Pi session, with its own store, kept apart from Pi's session file:

╭─ Pi process ─────────────────────────────────────────────────────╮
│                                                                  │
│  ╭─────────────────────────────────────╮ ╭────────────────────╮  │
│ ╭┤  ◆ Pi session: MCP, extension tools │ │  ▤ panel           │  │
│ ┊╰───┬──────────▲──────────────────────╯ │  ⇄ attach view     │  │
│ ┊    │ agent_*  │ results                │  ≡ /agents         │  │
│ ┊    ▼          │                        │  ✉ /messages       │  │
│ ┊╭──────────────┴───╮                    ╰─────────▲──────────╯  │
│ ┊│  ✦ pi-agents     ├◀─────────────────────────────╯             │
│ ┊╰───┬──────────▲───╯                                            │
│ ┊    │ start    │ state                                          │
│ ┊    │ message  │ results                                        │
│ ┊    ▼ stop     │                                                │
│ ┊╭──────────────┴─────────────────────────────────────────────╮  │
│ ┊│  pi-durable harness                                        │  │
│ ┊│                                                            │  │
│ ┊│   ◉ scout ─── message ──▶ ● notes                          │  │
│ ┊│                                                            │  │
│ ┊│   ╭─ graph ─────────────────────────╮  agent tools:        │  │
│ ┊│   │ ● map ─┬─▶ ◉ core ─┬─▶ ○ report │  read  bash  edit    │  │
│ ┊│   │        └─▶ ◉ ui ───┘            │  write  grep         │  │
│ ┊│   │            └─ ◉ ◉ ◉ helpers     │  find  ls  codemode  │  │
│ ┊│   ╰─────────────────────────────────╯                      │  │
│ ┊│                                                            │  │
│ ┊│   agents are conversations; turns, tool calls, and graphs  │  │
│ ┊│   are durable tasks that own what they start               │  │
│ ┊╰─────────────────────────────┬──────────────────────────────╯  │
╰─┬──────────────────────────────┬─────────────────────────────────╯
  ┊ saves                        │ checkpoint every step
  ▼                              ▼
╭──────────────────────╮    ╭──────────────────────────────╮
│ ▤ Pi's session file  │    │ ▤ pi-agents store, one per   │
│   your conversation, │    │   session: agents, graphs,   │
│   saved results, and │    │   messages, tasks            │
│   message cards      │    │                              │
╰──────────────────────╯    ╰──────────────────────────────╯

docs/architecture.md explains how agents, graphs, and results stay durable across crashes and restarts.

📚 Documentation

• Usage: glossary, states, skills, UI, commands, and tools.
• Graphs: coordinating agents and delegating to helpers.
• Messaging: using messages and their guarantees.
• Agent profiles: reusable settings and instructions.
• Configuration: models, requests, and footer counts.
• Architecture: durable tasks, recovery, and storage.