Background Task Runner

Run long-lived processes in a detached tmux session so they survive the shell session and don't block the agent timeout.

Workflow

1. Kill any old process on the port (if applicable):

   lsof -i :<port> 2>/dev/null | awk 'NR>1{print $2}' | xargs -r kill 2>/dev/null

1. Start the task in a named session:

   cd <project-dir> && tmux new-session -d -s <session-name> '<command>'

1. Verify — wait briefly, then capture output:

   sleep 2
   tmux capture-pane -t <session-name> -p

If the output shows errors, the command may have failed immediately.

1. Report — tell the user the session name, how to view logs

(tmux capture-pane -t <name> -p), how to stop (tmux send-keys -t <name> C-c && tmux kill-session -t <name>), and the URL/port if applicable.

Gotchas

• tmux must be installed — brew install tmux (macOS) or apt install tmux

(Linux). Check: which tmux.

• A session with the same name silently fails — kill the old one first.
• `capture-pane` shows only visible scrollback — for full logs, redirect output

to a file: tmux new-session -d -s <name> 'command > /tmp/log 2>&1'.

• Processes survive agent disconnects — the user must clean them up manually.