====== tmux and byobu ======

Terminal multiplexers: run multiple shell sessions inside a single SSH connection, detach and reattach without losing work.

  * **tmux** — the underlying multiplexer; powerful, scriptable, widely available
  * **byobu** — a configuration layer on top of tmux (or screen); adds a status bar, function-key bindings, and sane defaults; ideal for tilde servers

===== Why This Matters for SSH =====

When your SSH connection drops — network hiccup, laptop sleep, ISP timeout — any running process dies with it. With tmux/byobu, your session keeps running on the server. Reconnect and reattach to find everything exactly as you left it.

===== byobu — Quick Start =====

On tilde servers (tilde.pink, tilde.town) byobu is usually pre-installed.

**Enable auto-launch on login:**
<code bash>
byobu-enable      # starts byobu automatically on every SSH login
byobu-disable     # undo this
</code>

**Start/attach manually:**
<code bash>
byobu             # start or reattach to existing session
byobu-tmux        # explicitly use tmux backend
</code>

===== byobu Key Bindings =====

Byobu uses F-keys as its primary interface (no prefix chord needed).

^ Key ^ Action ^
| ''F1'' | Help / keybinding reference |
| ''F2'' | New window |
| ''F3'' | Previous window |
| ''F4'' | Next window |
| ''F5'' | Refresh status bar |
| ''F6'' | Detach session (keep running on server) |
| ''F7'' | Enter scrollback/copy mode |
| ''F8'' | Rename current window |
| ''F9'' | byobu configuration menu |
| ''Shift+F2'' | Split horizontally (new pane below) |
| ''Ctrl+F2'' | Split vertically (new pane right) |
| ''Shift+F3/F4'' | Move between panes |
| ''Shift+F6'' | Detach all clients (keep session running) |
| ''Alt+PageUp/Down'' | Scroll back through terminal history |

**Reattach after reconnecting:**
<code bash>
byobu             # reattaches to existing session automatically
</code>

===== tmux — Direct Usage =====

If byobu isn't available or you prefer direct control:

==== Sessions ====

<code bash>
tmux                          # new unnamed session
tmux new -s work              # new session named "work"
tmux ls                       # list sessions
tmux attach -t work           # attach to "work"
tmux attach                   # attach to most recent session
tmux kill-session -t work     # kill a session
</code>

==== Prefix Key ====

All tmux commands start with the **prefix**: ''Ctrl+b'' (default). Press prefix, then the command key.

==== Windows (tabs) ====

^ Keys ^ Action ^
| ''prefix c'' | New window |
| ''prefix ,'' | Rename window |
| ''prefix n'' | Next window |
| ''prefix p'' | Previous window |
| ''prefix 0–9'' | Jump to window by number |
| ''prefix w'' | Interactive window list |
| ''prefix &'' | Kill current window |

==== Panes (splits) ====

^ Keys ^ Action ^
| ''prefix %'' | Split vertically (left/right) |
| ''prefix "'' | Split horizontally (top/bottom) |
| ''prefix arrow'' | Move between panes |
| ''prefix z'' | Zoom pane to full screen (toggle) |
| ''prefix x'' | Kill current pane |
| ''prefix {'' / ''}'' | Swap pane left/right |
| ''prefix Ctrl+arrow'' | Resize pane |

==== Sessions and Detach ====

^ Keys ^ Action ^
| ''prefix d'' | Detach (session keeps running) |
| ''prefix s'' | List and switch sessions interactively |
| ''prefix $'' | Rename session |

==== Copy Mode (Scrollback) ====

<code>
prefix [          enter copy mode
arrow keys        scroll
Ctrl+s            search forward
q                 quit copy mode
Space             start selection (vi mode)
Enter             copy selection
prefix ]          paste
</code>

To enable vi-style keys in copy mode, add to ''~/.tmux.conf'':
<code>
setw -g mode-keys vi
</code>

===== Useful ~/.tmux.conf Settings =====

<code bash>
# Increase scrollback buffer
set -g history-limit 10000

# Start window numbering at 1
set -g base-index 1

# Mouse support (scroll, click to select pane)
set -g mouse on

# Vi keys in copy mode
setw -g mode-keys vi

# Reload config without restarting
bind r source-file ~/.tmux.conf \; display "Reloaded"

# More intuitive splits (same directory)
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
</code>

Reload after editing:
<code bash>
tmux source-file ~/.tmux.conf
# or prefix r if you added the bind above
</code>

===== SSH Workflow with tmux =====

**Typical session setup on a remote server:**
<code bash>
ssh you@tilde.pink
tmux new -s main          # or just: byobu

# inside tmux:
# window 1: shell / general work
# window 2: irssi / IRC
# window 3: neomutt / email
# window 4: editor

# when done for the day:
# prefix d  (detach — everything keeps running)
</code>

**Next day:**
<code bash>
ssh you@tilde.pink
tmux attach -t main       # or just: byobu
# back exactly where you left off
</code>

**Persistent processes** (keep running after detach): irssi, weechat, mutt/neomutt, a long compile, a server process — anything you'd otherwise need ''nohup'' or ''screen'' for.

===== mosh — Mobile Shell =====

[[https://mosh.org/|mosh]] is an alternative to SSH that handles intermittent connections gracefully — roaming between networks, laptop sleep, spotty mobile data. Uses UDP.

<code bash>
mosh you@tilde.pink       # instead of ssh
</code>

Combine with byobu/tmux for the most resilient remote workflow: mosh handles the connection layer, tmux handles session persistence.

===== tilde.pink Specific =====

<code bash>
byobu-enable              # auto-launch on login (run once)
</code>

byobu will start automatically every time you SSH in and reattach to your existing session if one exists. See [[tilde:pink|tilde.pink]] for other setup steps.

===== See Also =====
  * [[terminal:tools:start|Terminal Tools Index]]

  * [[tilde:pink|tilde.pink]]
  * [[tilde:start|tilde.town]]
  * [[terminal:tools:ssh_tilde|SSH — tilde.town]]
  * [[terminal:tools:ssh_homelab|SSH — Homelab]]
  * [[terminal:start|Return to terminal]]