tmux-task-manager

Tmux Task Manager

Use this skill for any project task that should not block the main line of work.

Typical cases:

• dev servers
• backend services
• watch mode commands
• log tailing / observation
• long scans or crawls
• polling / monitoring loops
• delayed or scheduled shell tasks
• parallel subtasks you want to keep alive

Do not use tmux for short one-shot commands when you need the output immediately in the current turn.

Rules

• Reuse the shared project tmux session in $PI_TMUX_SESSION.
• If $PI_TMUX_SESSION is missing, compute it with ./tmux-session-name.sh.
• Use one tmux window per logical task.
• Give each task a short, descriptive window name.
• Preferred names: web, api, worker, logs, watch, scan, tests, build.
• Avoid long names, timestamps, random suffixes, and vague names like task or misc.
• When rerunning the same task intentionally, replace the old same-name window.
• Once a window exists, prefer window id (@12) for follow-up operations.
• Notifications mention both id and name, e.g. @12 (web).

Session bootstrap

Prefer the injected value from the extension:

if [[ -z "${PI_TMUX_SESSION:-}" ]]; then
  PI_TMUX_SESSION="$(./tmux-session-name.sh)"
  export PI_TMUX_SESSION
fi

Ensure the shared session exists:

tmux has-session -t "$PI_TMUX_SESSION" 2>/dev/null || \
  tmux new-session -d -s "$PI_TMUX_SESSION" -n shell

Standard start / replace flow

TASK_NAME=web

EXISTING_WINDOW_ID="$({ tmux list-windows -t "$PI_TMUX_SESSION" -F '#{window_id}\t#{window_name}' || true; } \
  | awk -F $'\t' -v name="$TASK_NAME" '$2==name { print $1; exit }')"

if [[ -n "$EXISTING_WINDOW_ID" ]]; then
  tmux kill-window -t "$EXISTING_WINDOW_ID"
fi

tmux new-window -t "$PI_TMUX_SESSION" -n "$TASK_NAME" \
  "bash -lc 'cd \"$PWD\" && npm run dev'"

WINDOW_ID="$({ tmux list-windows -t "$PI_TMUX_SESSION" -F '#{window_id}\t#{window_name}' || true; } \
  | awk -F $'\t' -v name="$TASK_NAME" '$2==name { print $1; exit }')"

if [[ -n "$WINDOW_ID" ]]; then
  tmux setw -t "$WINDOW_ID" remain-on-exit on
fi