pi-tmux-subagents

Pi extension for launching Markdown-defined subagents as real tmux-backed Pi sessions. Use it to delegate focused coding-agent tasks to parallel child Pi sessions, track their results, and optionally mirror them inside pi-agent-hub.

Requirements

• Pi coding agent with package support.
• tmux available on PATH.
• Node.js 20 or newer for local development and npm installs.

Install

Install from npm:

pi install npm:pi-tmux-subagents

Restart any already-running parent Pi sessions after installing or updating; Pi loads extension code at process start.

Local development install:

git clone https://github.com/masta-g3/pi-tmux-subagents.git
cd pi-tmux-subagents
npm install
npm test
pi install "$PWD"

Re-run npm run build after local changes, then restart parent Pi sessions that should use the updated extension.

Agent files

The package ships with three built-in agents:

• scout — fast read-only codebase recon, pinned to openai-codex/gpt-5.4-mini.
• worker — focused implementation agent, pinned to openai-codex/gpt-5.5.
• delegate — lightweight general helper that inherits the parent model.

User agents are discovered from:

~/.pi/agent/agents/*.md

User/project agents with the same name override built-ins. Project agents are opt-in via agentScope: "project" or "both" and are discovered from the nearest:

.pi/agents/*.md

Example:

---
name: scout
description: Fast codebase recon
model: openai-codex/gpt-5.5
thinking: low
tools: read, bash
systemPromptMode: replace
inheritProjectContext: true
inheritSkills: false
---

You are a focused scouting agent. Report findings clearly and stop.

Tool usage

tmux_subagent({ action: "list" })
tmux_subagent({ action: "get", agent: "scout" })
tmux_subagent({ agent: "scout", task: "Inspect auth flow", background: true })
tmux_subagent({ agent: "code-critic", task: "Review these files" }) // auto-stops after clean completion by default
tmux_subagent({ agent: "scout", task: "Keep alive for follow-up", autoStopOnComplete: false })
tmux_subagent({ action: "send", childId: "abc123", message: "Now check edge cases.", wait: true })
tmux_subagent({ action: "wait", childId: "abc123", timeoutMs: 600000 })
tmux_subagent({ action: "status", childId: "abc123" })
tmux_subagent({ action: "stop", childId: "abc123" }) // or action: "cancel"

Child sessions auto-stop after clean completion by default so completed subagents do not clutter tmux or pi-agent-hub dashboards. Pass autoStopOnComplete: false when you want to inspect, attach, or send follow-up messages after completion, then use action: "stop" when done. Auto-stop only applies after clean completion; failed or interrupted sessions stay alive for inspection. Background jobs auto-stop when a later status call observes clean completion.

Persistent children support generic follow-up turns through action: "send". By default send returns after pasting the message into the live child; pass wait: true to wait for the next completed turn. action: "wait" waits for a running child to return to an idle/completed state and supports timeoutMs; timeouts leave the child alive for later inspection or stopping.

Each completed child turn writes a numbered result file under jobs/<id>/turns/, and jobs/<id>/result.md is updated to the latest result for compatibility with existing tooling.

Foreground runs and explicit status calls render a compact parent-session summary:

tmux subagent scout
 ✓ scout · done · 2m39s
   ⎿  Done
      <result preview>
   tmux: pi-agent-hub-abc123
   attach: tmux attach-session -t pi-agent-hub-abc123
   output: /path/to/result.md
   stop: tmux_subagent({ action: "stop", childId: "..." })

State is stored in PI_TMUX_SUBAGENTS_DIR, or <PI_CODING_AGENT_DIR>/pi-tmux-subagents when unset.

pi-agent-hub integration

The extension is standalone. When launched from a managed pi-agent-hub parent with PI_AGENT_HUB_DIR and PI_AGENT_HUB_SESSION_ID, it mirrors child rows into the hub registry and writes dashboard-compatible heartbeats. Without those env vars, no hub state is created or required.

Development

npm install
npm test
npm publish --dry-run