pi-ptc-subagents

pi ships no sub-agents. This is the package that adds them.

Programmable tool calling and subagent fan-out for pi. The model writes a JS/TS program that composes pi's tools, or fans out to a fresh pi subprocess per task — one round trip instead of many.

pi install npm:pi-ptc-subagents

pi reads the pi.extensions manifest — installed and on for the next startup. No postinstall hook, no extra setup.

01 Programmable tool calling

ptc_run_code / ptc_workflow run a JS/TS program in a worker. It reaches the session's tools as tools.<name>(args). Only the program's return value and its logs come back to the model.

PTC  Find AssistantMessageComponent instantiations
  ├─ file: "chat-viewport.ts"        • 1 output line · 1.42s
  ├─ instantiations: Array(3)
  │  ├─ [0] {file: "chat-viewport.ts", line: 23}
  │  ├─ [1] {file: "chat-viewport.ts", line: 47}
  │  └─ [2] {file: "chat-viewport.ts", line: 91}
  └─ totalLines: 47

02 Subagent fan-out

The pi.dispatch binding spawns a fresh pi subprocess per call, so each task gets its own context. Foreground await, or background with a lifecycle you can list, read and stop.

ptc_task_list
  ├─ t-3  audit the render path    running · 41s
  ├─ t-4  check the ADR links      running · 12s
  └─ t-2  verify-dist gate         done · exit 1

pi's core stays minimal. This is the package that fills the gaps.

pi's own product page lists the features it left out, and offers extensions or a third-party package as the alternative. Three of those gaps are what this package is for — the rest it composes with rather than replaces.

~~No sub-agents~~

→ fan-out, in-process or background

pi.dispatch plus ptc_task_list / ptc_task_output / ptc_task_stop. Session-level isolation without inventing a task state machine.

~~No plan mode~~

→ program the plan instead

Loops, branches and fan-out live in JavaScript, where the model can express them — not in a second tool protocol.

~~No background bash~~

→ long-lived, inspectable

Background dispatch hands back a handle, not a tmux pane. List it, read it, stop it.

What you get, by pi

Three configurations, three different answers. The subagents line exists because a QuickJS sandbox cannot spawn a process at all — handing the program face away there would delete the capability rather than hand it over.

Capability	pi alone	+ codemode	+ this
Write a program that composes tools`ptc_run_code` / `ptc_workflow`	—	✓	✓
A real Node runtime inside the programno OS sandbox	—	QuickJS	✓
Spawn a fresh `pi` subprocess`pi.dispatch`	—	—	✓
Background tasks you can list, read and stop`ptc_task_*`	—	—	✓
Top-level subagent call, no program needed`ptc_subagent`	—	✓	✓
Value-tree TUI renderingnever escaped JSON	—	—	✓

Two columns reading the same: on codemode the pair registers underneath as an execution layer, so a script can reach what the sandbox cannot.

Trust posture

Installing this package grants it the same machine access as any pi extension: PTC programs run as you, with no OS-level sandbox.

Bindings mirror the session's enabled built-in tools. A session started with --tools … can only reach those tools from inside a program.

Tool calls made from inside a PTC program execute directly and bypass pi's tool_call hooks — permission gates and path guards included. Do not rely on those guards while this extension is enabled.

Source is open and the repository is public — dist/ on npm is the compiled form of what you read. Read the source.