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
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
Install
Install the public npm package:
Or install directly from GitHub:
Choose only one source to avoid loading the extension twice. Then start Pi or run
Ask Pi to delegate work:
The model queries
Completion notices are intentionally small. Full answers enter the parent context only when explicitly requested with
Inspect sub-agent sessions
Use the user-only
The picker orders agents by latest task assignment, newest first; a successful
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
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:
Usage accounting
Pi's built-in
The command writes a detailed report directly into the normal TUI transcript, like
The report is stored as a TUI-only custom entry so it remains outside LLM context and does not affect
Tools
Only two compact collaboration schemas remain active:
```json
{
"action": "spawn_agents",
"arguments": {
"agents": [
{
"message": "Research the API implementation",
"task_name": "api_research",
"agent_type": "explorer"
},
{
"message": "Insp
…
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-agentsOr install directly from GitHub:
pi install git:github.com/YoungJurry/pi-agentsChoose 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_researchThe 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 downt/b: jump to the top or bottomCtrl+O: expand or collapse tool outputCtrl+T: show or hide thinkingr: refresh immediatelyEscape: return to the agent picker
/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-usageThe 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 viewroles: available roles and their tool accesstools: action descriptions and parameter schemasstatus: canonical agent-tree statusresults: stored final answersagent_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 queuesend_message: non-waking mailbox messagefollowup_task: assign more work and trigger processingwait_agent: event-driven mailbox wait; defaults to 30 seconds, with an optionaltimeout_msup to 2 hoursinterrupt_agent: abort a run without deleting contextswitch_agent_model: change an existing child's model without interrupting or waking it
```json
{
"action": "spawn_agents",
"arguments": {
"agents": [
{
"message": "Research the API implementation",
"task_name": "api_research",
"agent_type": "explorer"
},
{
"message": "Insp
…