pi-tmux

Tmux tools for pi to run long-running commands and control panes by lock name.

Requirements

• Must be running inside a tmux session (TMUX env var set)
• tmux must be installed
• pi-semaphore should be installed

Installation

pi install git:github.com/offline-ant/pi-tmux

Or try without installing:

pi -e git:github.com/offline-ant/pi-tmux

Tools

Tool	Description
tmux-bash	Create a new tmux pane with a lock name and execute a command (defaults to bash)
tmux-capture	Capture output from a pane by lock name or pane id
tmux-send	Send text or keys to a pane by lock name or pane id; for coordinated workflows, pair with semaphore_wait on the same lock name (unless the command launches a nested pi, then wait on the inner lock)
tmux-kill	Kill a pane by lock name or pane id
tmux-coding-agent	Spawn a pi coding agent in a pane and return startup output
minitask	Run multiple independent questions/tasks through pi -p in serial and return <question>/<answer> blocks

Lock + Pane Mapping

tmux-bash creates a lock in /tmp/pi-semaphores/<name>.

• The lock file content is the tmux pane id (for example %42)
• Control tools resolve <name> -> pane id and target that pane
• When the command exits, the lock is removed and idle:<name> is written

This allows any agent in the same tmux server to control panes it did not spawn, as long as it knows the lock name.

Example

1. Start: tmux-bash with name worker and command npm run dev
2. Capture: tmux-capture with name worker
3. Send keys: tmux-send with name worker and text C-c
4. Kill: tmux-kill with name worker

Spawn a coding agent:

1. tmux-coding-agent with name reviewer, folder ../project
2. tmux-send with name reviewer and text analyze lint failures
3. semaphore_wait with name reviewer

tmux-coding-agent runs pi without model arguments unless piArgs is set, so it uses pi's saved last active model by default. Pass --provider/--model in piArgs only when you want to override that selection.

Run independent quick tasks:

1. minitask with questions: ["What is module X?", "Give a one-line status of task Y"]
2. Read <question>...</question><answer>...</answer> blocks from output

Safety Policy

This extension blocks git restore when invoked through:

• built-in bash
• tmux-bash
• tmux-send

Blocked calls are denied before execution. Other work might be in progress; ask the user to resolve the issue if necessary.

Commands

• /tmux-list lists active tmux panes
• /supervise <task> spawns a supervised coding agent workflow: writes a task file to ./dev/scratch/<id>/task.md, then turns the current agent into a supervisor that spawns a 'main' agent to do the work. The supervisor keeps the main agent on track, enforces the >78% context handoff rule, and ensures architectural quality over speed — nudging the main agent to investigate properly and build well-structured solutions rather than rushing to quick fixes. The main agent is unaware it has a supervisor.

License

MIT