🤖 pi-agents

Give Pi durable, named agents. Delegate a task, 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.

🚀 Installation

pi install npm:pi-agents

✨ Usage

Ask Pi to delegate:

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.
Wait for both and merge their findings.

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

Pi starts agents only when you ask for delegation. An agent's result is its final message. Results of agents that Pi doesn't wait for arrive later as messages in your conversation. In a graph, agents pass their results to each other, and Pi gets one message at the end.

Every agent keeps its conversation. Open /agents, pick any agent, even one that finished hours ago, and keep talking to it like a regular Pi session.

Architecture

Agents run inside your Pi process. Pi-agents keeps one pi-durable harness per Pi session; each agent is a conversation in that harness:

╭─ Pi process ─────────────────────────────────────────────────────╮
│                                                                  │
│  ╭──────────────────╮                    ╭────────────────────╮  │
│  │  ◆ Pi session    │                    │  ▤ panel           │  │
│  ╰───┬──────────▲───╯                    │  ⇄ attach view     │  │
│      │ agent_*  │ results                │  ≡ /agents         │  │
│      ▼          │                        ╰─────────▲──────────╯  │
│  ╭──────────────┴───╮                              │             │
│  │  ✦ pi-agents     ├──────────────────────────────╯             │
│  ╰───┬──────────▲───╯                                            │
│      │ start    │ state                                          │
│      │ message  │ results                                        │
│      ▼ stop     │                                                │
│  ╭──────────────┴─────────────────────────────────────────────╮  │
│  │  pi-durable harness                                        │  │
│  │                                                            │  │
│  │   ╭─────────────╮   ╭─────────────╮   ╭─────────────╮      │  │
│  │   │ ◉ agent     │   │ ◉ agent     │   │ ● agent     │  …   │  │
│  │   ╰─────────────╯   ╰─────────────╯   ╰─────────────╯      │  │
│  │   one conversation per agent                               │  │
│  ╰─────────────────────────────┬──────────────────────────────╯  │
╰────────────────────────────────┼─────────────────────────────────╯
                                 │ checkpoint every step
                                 ▼
                   ╭───────────────────────────╮
                   │  ▤ JSONL, one per session │
                   ╰───────────────────────────╯

A graph is a task in the same harness that starts its agents in order and hands results along, so stopping a graph reaches all of its agents. Because pi-durable checkpoints every step, a resumed session continues where its agents and graphs stopped. Agents use your Pi logins and models, so they need no separate setup.

Glossary

An agent is in one of these states:

A graph uses the same glyphs: it works until all of its agents finished, then shows the state of its last agents: failed if one failed or was skipped, interrupted if one was interrupted or stopped, and idle otherwise.

Agents use Pi's tools read, bash, edit, write, grep, find, and ls, along with your context files such as AGENTS.md and your skills. They can't use MCP servers, tools from other extensions, or other agents.

Watch and talk to agents

A panel above the editor shows one line per open agent or graph, with a graph's agents below it as a tree. The glyph shows the state, working agents show how long they have worked, a graph shows how many of its agents finished, and ← names the agents whose results an agent receives:

◉ reviewer · explorer · terra · 1m32s · 15.5k · Using grep
✗ docs · sol · 8.0k · $0.02 · rate limit exceeded
◉ review · graph 1/4 · 40s · 12.0k
├─ ● api · terra · 4.0k
├─ ◉ tests · sol · 40s · 8.0k · Using grep
├─ ◉ host · sol · 40s
└─ ○ merge ← api, tests, host · opus

An agent leaves the panel once its answer reaches Pi, and a graph once its result does. Failed and interrupted agents stay until you or Pi stop them.

Press ← in an empty editor or Ctrl+Q to focus the panel. Then:

Attaching shows the agent's conversation with Pi's own message and tool rendering. The editor then talks to the agent:

Messages you send while attached stay between you and the agent. Their results don't post into the parent conversation.

You can attach to any agent, not only the ones in the panel. Agents that finished or were stopped keep their whole conversation: open /agents, select one, and continue where it left off. This also works for a graph's agents after the graph finished, and after you resume a session.

Graphs

A graph starts two to twelve agents that work together. Agents run in parallel, and an agent that waits for others starts once they finished and receives their final messages with its task. Common shapes:

Only the agents nothing waits for report back to Pi, as one message. With a single last agent, such as a merging one, Pi gets just its answer, and the results in between stay in the graph, where you can attach to read them:

● review › merge answered · opus · 6.2k
  Three issues stand out: …
✗ host failed: rate limit exceeded

When an agent that others wait for fails, they still start with the results that did arrive, and learn which agent failed. An agent is skipped only when none of the agents it waits for answered.

By default a graph runs to the end, even when an agent fails. Ask Pi to stop everything as soon as one agent fails, and the remaining agents stop instead. Stopping a graph stops all of its agents and posts nothing. Interrupting or stopping a single agent doesn't stop its graph or the graph's other agents.

A graph's agents are ordinary agents: attach to them, message them, and keep talking to them after the graph finished. A message to a graph's agent while the graph works joins its work; if the agent answers it separately, that answer arrives after the graph's result. A queued follow-up to a graph's agent holds back the graph until the agent answered it as well.

Graphs replace the workflow language of earlier versions with something smaller: edges carry final messages, and there are no references, schemas, loops, or conditions. For repeated rounds, such as review and fix, Pi can message the agents again.

Commands

Tools

Pi uses these tools to work with agents:

agent_spawn, agent_spawn_graph, and agent_send can also block for the result: their wait argument sets the most seconds to wait. A result that a wait returns doesn't post again as a message. Cancelling a wait leaves the agents working, and so does a message you send to Pi while it waits: Pi stops waiting and answers you right away.

Each tool call shows the arguments Pi chose on a dim line below it:

✦ spawn lister
  profile=explorer thinking=low tools=[read,ls] wait=120s
  List the files in src and summarize them.

Durability

Agents belong to the Pi session that started them. When you quit Pi or it crashes, agents pause. When you resume the session, for example with pi -c, interrupted work continues and results that haven't arrived yet post into the conversation. A graph continues too: its agents that already finished don't work again, and no agent gets its task twice. A tool call that can't safely repeat reports the interruption to the agent instead.

Agents of sessions started with --no-session live in memory and end with the session.

🧑‍💻 Agent profiles

A profile bundles reusable settings for agents. Create .pi/agents/planner.md:

---
name: planner
description: Maps a codebase and proposes implementation plans
model: claude-opus-4-5
thinking: high
tools: [read, grep, find, ls]
skills: [architecture]
---

Map the relevant code and return a concrete implementation plan with file
paths. Do not edit files.

Then ask for it:

Have a planner agent plan the caching layer.

Profile fields:

The Markdown body extends the agent's system prompt. Arguments that Pi passes to agent_spawn override profile settings.

Pi-agents reads profiles from ~/.pi/agent/agents and from the nearest project .pi/agents. Project profiles win over user profiles with the same name.

⚙️ Configuration

Models

An agent runs on your session's model unless Pi or a profile picks another. Models resolve like pi --model: sonnet picks the newest Sonnet you have credentials for, and an exact ID such as claude-sonnet-4-6 picks that version. Run pi --list-models to see what's available.

Pi learns which names are models from your scoped models, the ones you pick with /scoped-models or --models. Scope the models you want agents to use, and Pi picks them by name: "spawn a Luna agent" runs on your scoped Luna.

Footer counters

With pi-fancy-footer installed, pi-agents can show open agents by state, such as ✦ 2◉ 1●. Enable the agents widget through /fancy-footer.