pi-tmux-task

Pi extension package for Pi-session-scoped background task management with tmux.

It does not implement a scheduler or replace tmux. It gives Pi a simple convention:

• one Pi session = one tmux task session;
• one logical task = one named tmux window / task slot;
• long-running work is started with helper scripts and observed by the Pi extension.

What you get

• Agent skill: tmux-task-manager
  • Guides the agent to use background tasks for dev servers, watch commands, long tests, scans, reminders, recurring checks, and log tails.
• Slash command: /tmux-tasks
  • Opens a task panel in TUI mode, or prints a text summary without TUI.
• Bash integration:
  • Every Pi bash call receives PI_TMUX_SESSION=<current-session-task-session>.
• Helper CLI:
  • pi-tmux-task-run
• Task notifications:
  • Task exit, terminal bell, input wait, and unexpected disappearance can notify the active Pi conversation.

Session naming

The tmux session name is:

pi-<project-slug>-<session-id>

Example:

pi-pi-tmux-task-019e4988-b257-7be4-a6f7-b945f8fb7d36

project-slug comes from the current directory basename. The full Pi session id scopes tasks to one Pi conversation.

Because the slug uses only the basename, different checkout paths with the same directory name share the same project prefix. Startup cleanup and notices are best-effort by project slug, not strict absolute-path ownership.

Installation

Install the package with Pi:

pi install npm:pi-tmux-task

To pin a specific version:

pi install npm:pi-tmux-task@0.1.0

For project-local installation, write the package entry to .pi/settings.json:

pi install -l npm:pi-tmux-task

You can also try the package for one Pi run without saving it to settings:

pi -e npm:pi-tmux-task

This package requires tmux to be available on PATH. After installation, Pi loads the bundled extension and the tmux-task-manager skill from the package.

Usage

Ask Pi to run long-lived work in the background, for example:

Start the dev server as a background task.

The bundled skill guides the agent to use a Pi-session-scoped tmux session for dev servers, watch commands, long tests, scans, reminders, recurring checks, and log tails.

Start or rerun a background task manually:

pi-tmux-task-run api-server -- 'npm run dev'

If running from this repository without installing the package bin links:

./skills/tmux-task-manager/tmux-task-run.sh api-server -- 'npm run dev'

Inside Pi, the extension injects PI_TMUX_SESSION into bash tool calls, so helper commands automatically target the current conversation's task session.

pi-tmux-task-run intentionally does not compute or guess the session name. If PI_TMUX_SESSION is missing, fix the Pi extension/environment instead of exporting an ad-hoc value.

Inspect tasks in Pi:

/tmux-tasks

Clean dead/exited task windows without touching running tasks:

/tmux-tasks prune-dead

Kill the entire current Pi task session after confirmation:

/tmux-tasks kill-all

Inspect tmux directly:

tmux list-windows -t "$PI_TMUX_SESSION" -F '#{window_id}\t#{window_name}'
tmux capture-pane -pt @12 -S -80

Cleanup behavior

Pi shutdown cleans up the current tmux task session when it has no active tasks. Sessions that are missing, empty, or contain only dead/exited task windows are removed automatically. If any task is still active, the session is preserved so long-running work can continue after Pi exits.

On the next Pi startup, the extension also scans same-project historical tmux sessions:

• sessions with no active tasks are cleaned automatically;
• sessions with active tasks are left running and reported to the user with a UI notice;
• these startup notices are not sent to the agent conversation and do not trigger an agent turn.

Manual cleanup remains available through /tmux-tasks prune-dead, /tmux-tasks kill-all, or direct tmux commands.

Documentation

• Architecture and lifecycle
• Task event flow

License

MIT. See LICENSE.

Development

Install dependencies:

npm install

Run checks:

npm run check

There is no separate build step; Pi loads the TypeScript extension source directly.