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.37.0
Published: Oct 21, 2026
Downloads: 3,737/mo · 994/wk
Author: mavam
License: MIT
Types: extension
Size: 566.8 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.

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

🚀 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 spawn agents: it finds every module under src, has
one agent review each, and returns one merged review.

Pi starts agents only when you ask for delegation. They work in the background and return their final messages to your conversation. In a graph, agents pass results to each other and Pi gets one message at the end.

🏗️ Architecture

Agents run inside Pi and use your Pi logins and models:

╭─ Pi process ─────────────────────────────────────────────────────╮
│                                                                  │
│  ╭──────────────────╮ ╭────────────────────╮ ╭────────────────╮  │
│ ╭┤ ◆ Pi session:    │ │ ◇ optional         │ │ ▤ panel        │  │
│ ┊│   MCP, extension │ │   extensions, e.g. │ │ ⇄ attach view  │  │
│ ┊│   tools          │ │   pi-service-tier  │ │ ≡ /agents      │  │
│ ┊│                  │ │                    │ │ ✉ /messages    │  │
│ ┊╰───┬─────────▲────╯ ╰─────────┬──────────╯ ╰────────▲───────╯  │
│ ┊    │ agent_* │ results        ╎ hooks: capture at   │          │
│ ┊    │         │                ╎ spawn, hold calls,  │          │
│ ┊    ▼         │                ▼ adapt requests      │          │
│ ┊╭─────────────┴──────────────────────────────────────┴───────╮  │
│ ┊│  ✦ pi-agents: a thin bridge from Pi to pi-durable          │  │
│ ┊╰───┬─────────▲──────────────────────────────────────────────╯  │
│ ┊    │ start   │ state                                           │
│ ┊    │ message │ results                                         │
│ ┊    ▼ stop    │                                                 │
│ ┊╭─────────────┴──────────────────────────────────────────────╮  │
│ ┊│  pi-durable harness                                        │  │
│ ┊│                                                            │  │
│ ┊│   ◉ scout ─── message ──▶ ● notes                          │  │
│ ┊│                                                            │  │
│ ┊│   ╭─ graph ─────────────────────────╮  agent tools:        │  │
│ ┊│   │ ● map ─┬─▶ ◉ core ─┬─▶ ○ report │  read  bash  edit    │  │
│ ┊│   │        └─▶ ◉ ui ───┘            │  write  grep         │  │
│ ┊│   │            └─ ◉ ◉ ◉ spawned     │  find  ls  codemode  │  │
│ ┊│   ╰─────────────────────────────────╯                      │  │
│ ┊│                                                            │  │
│ ┊│   agents are conversations; turns, tool calls, and graphs  │  │
│ ┊│   are durable tasks that own what they start; model        │  │
│ ┊│   requests pass the hooks with each agent's snapshot       │  │
│ ┊╰─────────────────────────────┬──────────────────────────────╯  │
╰─┬──────────────────────────────┬─────────────────────────────────╯
  ┊ saves                        │ checkpoint every step
  ▼                              ▼
╭──────────────────────╮    ╭──────────────────────────────╮
│ ▤ Pi's session file  │    │ ▤ pi-agents store, one per   │
│   your conversation, │    │   session: agents and their  │
│   saved results, and │    │   hook snapshots, graphs,    │
│   message cards      │    │   messages, tasks            │
╰──────────────────────╯    ╰──────────────────────────────╯

📚 Documentation

Usage: glossary, states, skills, UI, commands, and tools.
Graphs: coordinating agents, and agents that spawn agents.
Messaging: using messages and their guarantees.
Agent profiles: reusable settings and instructions.
Configuration: models, requests, and footer counts.
Architecture: recovery, storage, and lifecycle events.
Extension hooks: capture settings, hold calls, and adapt requests.