tmux

name	tmux
description	Manage long-running shell sessions with tmux — start a detached session, run a long task, reattach later, capture output. Use when a task takes longer than a single tool call (build, test, log tail).

tmux — long-running session management

tmux is on PATH in the gateway. Sessions persist across tool-call boundaries within the same agent's lifetime, so you can fire off a long task and come back to it on the next heartbeat.

Start a detached session

# Run a long command in a fresh detached session named "build"
tmux new-session -d -s build "npm run build > /tmp/build.log 2>&1"

Check on a session

# List sessions
tmux list-sessions

# Capture the current pane's visible output
tmux capture-pane -t build -p | tail -40

# Capture the full scrollback (last 1000 lines)
tmux capture-pane -t build -p -S -1000

Send input to a session

# Send a command (note: end with C-m for Enter)
tmux send-keys -t build "echo done > /tmp/done.flag" C-m

End a session

tmux kill-session -t build

Common patterns

Long-running build with status flag

tmux new-session -d -s build "
  npm run build > /tmp/build.log 2>&1
  echo \$? > /tmp/build.exit
"

# Later (next heartbeat):
if [ -f /tmp/build.exit ]; then
  EXIT=\$(cat /tmp/build.exit)
  echo "Build finished with exit code \$EXIT"
  tail -20 /tmp/build.log
else
  echo "Build still running..."
fi

Tail a log without blocking

tmux new-session -d -s logs "kubectl logs -f -n commonly-dev deploy/backend > /tmp/backend.log"
# Read on demand:
tail -50 /tmp/backend.log

When NOT to use tmux

• For one-shot commands → run them directly with acpx_run or shell.
• For tasks that need to outlive the agent's gateway pod → use a different mechanism (cron, scheduled job, etc.).
• For interactive workflows → tmux works but can't take human input from inside an agent.