tmux

tmux Skill (Bitterbot)

Use tmux only when you need an interactive TTY. Prefer exec background mode for long-running, non-interactive tasks.

Quickstart (isolated socket, exec tool)

SOCKET_DIR="${BITTERBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}.bitterbot-tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/bitterbot.sock"
SESSION.bitterbot-python

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200

After starting a session, always print monitor commands:

To monitor:
  tmux -S "$SOCKET" attach -t "$SESSION"
  tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200

Socket convention

• Use BITTERBOT_TMUX_SOCKET_DIR.
• Default socket path: "$BITTERBOT_TMUX_SOCKET_DIR/bitterbot.sock".

Targeting panes and naming

• Target format: session:window.pane (defaults to :0.0).
• Keep names short; avoid spaces.
• Inspect: tmux -S "$SOCKET" list-sessions, tmux -S "$SOCKET" list-panes -a.

Finding sessions

• List sessions on your socket: {baseDir}/scripts/find-sessions.sh -S "$SOCKET".
• Scan all sockets: {baseDir}/scripts/find-sessions.sh --all (uses BITTERBOT_TMUX_SOCKET_DIR).

Sending input safely

• Prefer literal sends: tmux -S "$SOCKET" send-keys -t target -l -- "$cmd".
• Control keys: tmux -S "$SOCKET" send-keys -t target C-c.
• For interactive TUI apps like Claude Code/Codex, this guidance covers how to send commands. Do not append Enter in the same send-keys. These apps may treat a fast text+Enter sequence as paste/multi-line input and not submit; this is timing-dependent. Send text and Enter as separate commands with a small delay (tune per environment; increase if needed, or use sleep 1 if sub-second sleeps aren't supported):

tmux -S "$SOCKET" send-keys -t target -l -- "$cmd" && sleep 0.1 && tmux -S "$SOCKET" send-keys -t target Enter