101 online 3 members  + Join RP Base  +
FreeScript

pi-agents

by YoungJurry  ·  version 2026.11.07  ·  updated 3 days ago

No reviews yet

Downloads
0
Reviews
0
Size
107 KB
Code check
Clean
Licence
MIT
Released
Nov 2026

Persistent in-process Codex-style multi-agent collaboration for Pi

pi-agents
Codex-style Agents for Pi
In-process persistent multi-agent collaboration modeled after OpenAI Codex MultiAgentV2.

Requires Pi 1.5.0 or newer. Root-agent guidance uses Pi's native multi_agent_role system-prompt section, preserving other extensions' sections and avoiding full-prompt replacement.
Install
Install the public npm package:

pi install npm:@youngjurry/pi-agents

Or install directly from GitHub:

pi install git:github.com/YoungJurry/pi-agents

Choose only one source to avoid loading the extension twice. Then start Pi or run /reload in an existing session.

This extension runs child agents with the same OS user and filesystem permissions as the root Pi process. Review SECURITY.md before using it on untrusted work.
Quick start
Ask Pi to delegate work:

Spawn two agents to research independent parts of this task, wait for completion,
then pull and summarize their results.

The model queries list_agents(view="tools") for the action catalog and, when needed, list_agents(view="roles") for role-specific configuration. It executes catalog actions through the compact agent_action dispatcher.

Completion notices are intentionally small. Full answers enter the parent context only when explicitly requested with list_agents(view="results").
Inspect sub-agent sessions
Use the user-only /agents command to browse the current root session's sub-agents and open a read-only transcript:

/agents
/agents /root/api_research

The picker orders agents by latest task assignment, newest first; a successful followup_task moves a reused agent back to the top without letting ordinary streaming or tool activity reshuffle the list. It shows lifecycle status, model, effective thinking level, role, nickname, and residency. Selecting an agent opens its active session branch with normal Pi-style assistant messages, thinking, tool calls, tool results, and collaboration messages. Custom tools reuse their original Pi renderers, so tools such as web_search and fetch stay as compact as they are in the main transcript. Running sessions refresh while the viewer is open. Child permission dialogs wait behind the inspector and appear only after the user fully exits /agents, so they cannot steal focus from or hide behind its overlay.

The open transcript inspector reuses native tool components and displays live partial output. Its footer distinguishes tool execution time from model response, waiting, and retry time, updating once per second even when no output arrives. Timings are collected for live loaded sessions, not reconstructed for historical sessions. Explicitly interrupted runs remain interrupted and do not emit failure notices for cancellation exceptions.

The main status bar and agent tree update only when their displayed state changes; streaming text alone does not request another tree redraw. Loaded transcript views reuse the live session manager, while unloaded views read the stored session.

Viewer controls:

  • ↑ / ↓: move one line
  • ← / →: move one page up or down
  • t / b: jump to the top or bottom
  • Ctrl+O: expand or collapse tool output
  • Ctrl+T: show or hide thinking
  • r: refresh immediately
  • Escape: return to the agent picker

This inspector is implemented only as a slash command and TUI overlay. It does not register an LLM tool, alter tool schemas or system prompts, add messages to the root context, switch sessions, wake agents, or expose child sessions through the normal /resume picker.
Usage accounting
Pi's built-in /session remains the authoritative view of the main Agent and its cache behavior. Use the user-only command below for separately calculated main, sub-agent, and combined totals:

/agent-usage

The command writes a detailed report directly into the normal TUI transcript, like /session; it does not open an overlay. The report includes main, sub-agent, and combined input/output/cache/token/cost totals, followed by separate main-model and sub-agent-model breakdowns. Each model row shows its tokens, prompt/output/cache details, number of contributing Agent sessions, and number of usage records. Non-model tool and summary usage is kept in an explicit Tools/summaries bucket rather than being misattributed to a model.

The report is stored as a TUI-only custom entry so it remains outside LLM context and does not affect /session message or token accounting. Reading the report does not load or wake child AgentSessions. Pi currently has no extension hook that can add child tokens to built-in /session while excluding them from that command's cache statistics.
Tools
Only two compact collaboration schemas remain active:

  • list_agents: query one catalog or data view
  • roles: available roles and their tool access
  • tools: action descriptions and parameter schemas
  • status: canonical agent-tree status
  • results: stored final answers
  • agent_action: execute a catalog action by name with its matching arguments

list_agents(view="tools") returns these actions as ordinary tool-result content instead of activating more provider tool schemas:

  • spawn_agents: submit one or many persistent child tasks in a single action; overflow waits in the visible FIFO queue
  • send_message: non-waking mailbox message
  • followup_task: assign more work and trigger processing
  • wait_agent: event-driven mailbox wait; defaults to 30 seconds, with an optional timeout_ms up to 2 hours
  • interrupt_agent: abort a run without deleting context
  • switch_agent_model: change an existing child's model without interrupting or waking it

Example dispatcher call:

```json
{
"action": "spawn_agents",
"arguments": {
"agents": [
{
"message": "Research the API implementation",
"task_name": "api_research",
"agent_type": "explorer"
},
{
"message": "Insp

…