pi-agents

Durable, named agents for Pi: delegate tasks, compose agents into graphs, and watch them work.

Packages

Package details

extension

Install pi-agents from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:pi-agents

Package: pi-agents
Version: 0.32.2
Published: Oct 15, 2026
Downloads: 3,191/mo · 2,362/wk
Author: mavam
License: MIT
Types: extension
Size: 469.9 KB
Dependencies: 3 dependencies · 4 peers

Pi manifest JSON

{
  "extensions": [
    "./src"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

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

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