version: "1.0.1" name: tmux-pi description: | Delegate and oversee work in tmux-hosted Pi agents. Triggers: "🧵", "thread", "delegate", "orchestrate", "oversee", "worktree", "spawn". Use for launching, monitoring, following up with, or coordinating delegated Pi work.

tmux-pi

Delegate work

Delegate work to another Pi:

• In the current tmux session and working directory by default.
• In another existing repo or worktree tmux session with --target.
• In a new worktree and tmux session with --worktree. This pulls local main first and creates the branch from its updated HEAD unless --source-ref is supplied.

Delegation remains supervised without blocking the parent. tmux-pi launches the child with the parent Pi session ID, reports the child Pi session ID and tmux window, then returns. The pi-ipc extension notifies the parent after every child agent_settled event.

Launch the delegate

For --task-slug choose a human-readable lowercase task slug of at most 13 characters using only letters, numbers, and internal hyphens; it must start and end with a letter or number. tmux-pi only accepts prompt files. Use an existing issue, plan, design, or spec, or write generated prompt text to a temporary file first.

Whe running tmux-pi, confirm the launcher reaches Launched; if slow worktree setup moves the command to the background, wait only for its automatic completion notification and do not poll it.

Current tmux session and working directory:

tmux-pi \
  --task-slug 'auth-research' \
  --prompt-file '<prompt-file>'

Another existing repo or worktree tmux session:

tmux-pi \
  --task-slug 'auth-research' \
  --prompt-file '<prompt-file>' \
  --target '<repo-or-worktree>'

New worktree from local main HEAD always uses the strongHigh profile:

tmux-pi \
  --task-slug 'auth-research' \
  --prompt-file '<prompt-file>' \
  --worktree '<branch>' \
  --model "openai-codex/gpt-5.6-sol" \
  --thinking "high"

Add --source-ref '<ref>' only when the worktree should start from an explicit source ref. Add --pi-session, --model, or --thinking when supplied by the request. Skill metadata delegates use --skill, which marks the child without exposing the internal environment variable at the call site.

tmux-pi launches the child with PI_DELEGATE=1, PI_DELEGATE_PARENT_SESSION_ID=<parent-session-id>, and PI_DELEGATE_TASK_SLUG=<task-slug>, then returns. Keep the task, child Pi session ID, and window from its output available for supervision.

Child will let you know when it's finished; no need to wait or poll. Do not use capture-pane, bash_process, sleep, or repeated status commands while waiting. Inspect the pane only if the notification is incomplete or the user explicitly requests live monitoring.

Oversee delegated work

When pi-ipc delivers a delegate-settled notification, use the delegated status embedded in the notification as the primary report. Do not run pi-jq again unless the embedded status is incomplete, reports an inspection failure, or richer diagnostics are necessary. Use tmux capture-pane only if session inspection fails or terminal-only state is required.

Use pi-jq

For fallback inspection, pi-jq <session-id> --messages 1 --role assistant --chars 5000 prints the latest answer without repeating the delegated request. Use --messages 3 when recent conversational context is necessary, --turn for richer diagnostics with the latest request, status, tools, and errors, --errors for failures, --log for the whole compact conversation, --path for the JSONL path, and --json for structured output. IDs may be shortened to a unique prefix.

If pi-jq needs another feature, read ~/code/nix-private/CLAUDE.md, edit ~/code/nix-private/flake/modules/home-manager/dot-files/Scripts/pi-jq, and run just switch from ~/code/nix-private to deploy it.

If the task remains unresolved, send follow-up instructions with tmux send-keys. The child will notify the parent again when the follow-up turn settles; assess the fresh embedded status directly before deciding whether more work is needed.

Never type multiline follow-up messages into Pi with tmux send-keys. Write the message to a file under /tmp, then send its absolute @ file reference as one line:

followup_file=/tmp/pi-followup-<task>.md
# Write the multiline instructions to "$followup_file" with the write tool.
tmux send-keys -t '<window-id>' "@$followup_file" Enter

For skill delegates, close the delegated tmux window after confirming the task is resolved:

tmux kill-window -t '<window-id>'

Worktree delegates are the exception: leave their tmux windows open after completion for human follow-ups. Do not kill a worktree delegate's window unless the user explicitly asks.

After launch, end the current turn with a brief delegation-in-progress status; do not claim the task is complete. pi-ipc will start or steer a later parent turn when the child settles. Then resume supervision and do not present the task as complete while notified work remains unresolved.