pi-delegate

English | 简体中文

Delegate focused tasks to fresh Pi subagents without leaving your current session.

pi-delegate is a TypeScript extension for Pi. It launches one-off subagents over RPC, with synchronous results or opt-in background execution.

Features

• Fresh subagents: each task runs in a new session; delegation tools are available only to the parent agent.
• Tool inheritance: reconstruct the parent's tools and extensions, preserving activation and discoverability.
• Synchronous and background execution: wait for a result or continue working while a session-owned task runs.
• Task management: discover synchronous/background tasks, inspect retained results, and manage background work in a floating /delegates TUI panel or through tools.
• Runtime steering: add context, narrow scope, or request a report from an active background child without restarting it.
• Soft pressure and status UI: configure task-local finish reminders and monitor subagents above the TUI input.
• Opt-in execution budgets: disclose per-task time/turn limits upfront and cancel on either observed threshold, independently of advisory pressure.

Requirements

• Git and Bun 1.4.1 or later for local setup.
• Node.js 22.19 or later. When Pi runs under Bun, node must be available on PATH for child processes.
• A compatible Pi host. This extension is validated with @earendil-works/pi-coding-agent@1.1.0; other host versions are not currently verified.

Installation

Install from npm

pi install npm:@wangjq4214/pi-delegate

The npm package includes the built extension and worktree skill; no local build is required.

Local development setup

Run the following from the root of a local Git checkout:

bun install --frozen-lockfile
bun run hooks:install
bun run build

Development Git hooks are installed explicitly with bun run hooks:install; npm consumers do not run development hooks. See the development guide.

Load the extension directly

bun run --cwd packages/pi-delegate pi --extension ./src/index.ts

Pi loads the TypeScript source directly; no build step is required.

Install as a local Pi package

With Pi CLI installed:

pi install /absolute/path/to/checkout/packages/pi-delegate

The package declares the built dist/index.js extension and bundled delegate-worktree skill in package.json. Install dependencies and run bun run build before installing a local checkout.

This package is now under packages/pi-delegate in a Bun workspace. The root is private; pack/publish from this package directory. See the workspace overview.

Usage

The parent agent can call delegate with a task and the context it needs:

{
  "task": "Review error handling in src/ and report findings with file paths",
  "context": "Analyze only; do not modify files"
}

By default, the call waits for the child's final outcome. To continue working while the child runs, opt into background mode:

{
  "task": "Analyze test coverage and report gaps",
  "context": "Analyze only; do not modify files",
  "background": true
}

Background outcomes do not send automatic completion messages or wake the parent. Use delegate_list to discover tasks and delegate_status to retrieve results on demand.

In TUI mode, /delegates opens one floating list → details → confirmation/instruction panel. Synchronous IDs are read-only: independent cancellation and steering remain background-only. Records/results survive five-second compact-row expiry, but not scope invalidation; the panel does not require pi-open-tui.

Optional execution limits work in either mode:

{ "task": "Analyze the core risks and report unfinished work honestly", "budget": { "maxSeconds": 120, "maxTurns": 8 } }

Each omitted dimension is unlimited; no default hard budget is added. Seconds must be positive/finite and turns positive integers (zero is invalid). The child receives the limits before working. Time excludes queue/init but includes provider/tool waits; turns are completed assistant responses with associated tools. Either observed threshold cancels without extra reporting generation. Results distinguish budget cancellation and retain available partial text/usage; effects are not rolled back and process shutdown is not instantaneous. See execution budgets.

See the usage guide for parameters, result states, pressure settings, and the status UI.

Limitations

• Background execution requires a long-lived TUI or RPC session. Tasks do not survive exit, reload, session replacement, or branch navigation.
• Parent and child agents share the working directory by default; optional cwd selects another existing directory. The bundled delegate-worktree skill guides parent-managed Git workspaces; the extension does not manage worktrees, enforce filesystem isolation, or provide an operating-system sandbox.
• The parent's full conversation is not copied automatically. Supply relevant context explicitly.
• Soft pressure is advisory, not a hard timeout. Background usage is reported separately from Pi's parent-session totals.
• Steering returns RPC handling receipts, not model-consumption or completion confirmation; initialization returns not_ready, and a timeout is uncertain, not a reason to retry automatically.

See runtime and safety for inheritance, lifecycle, interaction, and cleanup boundaries.

Documentation

• Usage guide — tools, parameters, results, pressure, and TUI behavior.
• Runtime and safety — tool inheritance, process ownership, cancellation, and security boundaries.
• Development guide — setup, checks, tests, Git hooks, and repository layout.
• Roadmap — prioritized capability candidates and TODOs.

The detailed documentation is maintained in English.

Contributing

See the development guide before making changes. Run the documented checks and tests, and keep the English and Chinese READMEs aligned when updating project-level documentation.

License

MIT. See the workspace root for the full license text.