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
bash# 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
bash# 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
bash# 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
bashtmux kill-session -t build
Common patterns
Long-running build with status flag
bashtmux 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
bashtmux 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_runor 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.

