$ cat ~/map/pi-background-task.md

pi-background-task

Six tmux-backed tools that start long-running commands, page bounded logs, send input, wait, and stop jobs.

extensions✓ Sep 11

pi install npm:pi-background-task

## TL;DR

A pi extension with six tmux-backed tools for long-running commands: start jobs, page bounded logs by byte offset, send terminal input, wait without model polling, and stop tasks, with durable full-output capture.

## Key points

• $Six agent tools — task_start, task_status, task_logs, task_send, task_wait, task_kill — cover the background-job lifecycle; task_start returns immediately with a task ID.
• $Every task runs in a real tmux PTY with the full output stream captured via pipe-pane; task_logs pages it by byte offset using the returned nextOffset, capped at 64 KiB per read so a noisy process cannot flood model context.
• $task_wait waits for any or all tasks inside one tool call, and completion notifications wake Pi only when a job finishes — no LLM polling loop.
• $task_send delivers literal text, Enter, or an allow-listed control key to shells, REPLs, debuggers, and TUIs; /bg-attach prints the exact tmux attach command instead of taking over Pi's terminal.
• $Task visibility follows Pi's session tree: /resume, /fork, /new, and branch switching keep unrelated histories apart, and reload, resume, fork, and new-session transitions do not kill jobs.
• $Requires pi 0.85.1 or newer, Node.js 20+, and tmux on PATH, on macOS or Linux; Windows users can run Pi inside WSL.

## FAQ

## References

• README ↗

Last updated: Sep 11, 2026