Moshi with tmux

Networks on a phone are hostile: you walk into an elevator, switch from Wi-Fi to cell, the screen sleeps, an app gets killed. tmux is the answer to all of it. It keeps your shells, agents, and TUIs running on the host, decoupled from whether your phone is connected right now. Moshi treats tmux as a first-class citizen — detecting it, listing its sessions, and shipping a shortcut panel — but you get the most out of the pairing when you shape tmux for a small screen.

This guide goes past "how to attach." It's about building a workspace you can actually run from your thumb.

What you'll learn

• Why durable sessions are the foundation of remote agent work
• The moshi launcher and an attach-or-create habit
• A window-per-task layout that survives a phone screen
• Swipe-to-switch, the shortcut panel, and prefix customization
• Copy mode and scrollback tuned for touch
• A small tmux config that makes mobile life better

Durable sessions, the foundation

When you SSH or mosh in and run an agent directly in the shell, that agent's life is tied to the connection. Drop the connection and you may kill the agent mid-turn. Run it inside tmux and the connection becomes a view onto a session that keeps running without you.

That single property — the session outlives the connection — is what makes everything else in Moshi safe: backgrounding the app, walking between networks, locking the phone for an hour. For any long-running agent, build, test suite, or server, tmux is the default, not an optional extra.

Start or attach

After installing moshi-hook you get a short moshi launcher for project sessions. It resolves the directory, names the session after the basename, and execs into tmux:

$cd ~/projects/app
$moshi .
$moshi ~/a/b/name
# resolves dir, names session, attaches-or-creates

Because it replaces itself with tmux, no Moshi wrapper process lingers. If you prefer raw tmux, the equivalent attach-or-create form is the one habit worth memorizing — it never errors whether the session exists or not:

$tmux new-session -A -s app -c ~/projects/app
# -A: attach if it exists, otherwise create

Reattach later from any new connection:

$tmux a -t app

A window-per-task layout

On a desktop you might split a window into panes. On a phone, panes are cramped — a one-window-per-task layout is far easier to control, and it maps cleanly onto how you think: one window per agent, one for logs, one for a server, one for ad-hoc shell work.

$tmux new-window -n agent
$tmux new-window -n server
$tmux new-window -n logs
$tmux rename-window shell

Keep names short and meaningful — they show up in tmux's status line and ride along in Moshi's session context, so a good name pays off in two places.

Panes still earn their place for a compact split — an agent above, a tail -f below. Use them sparingly:

Switching windows the Moshi way

Typing Ctrl-B N on a phone keyboard is exactly the friction Moshi removes. When live detection sees you're inside a tmux pane, you get two faster paths:

• Swipe left/right in the terminal to move between windows.
• The shortcut panel under the keyboard has a window quick-access row (1–20) and Next/Previous buttons.

Both send your tmux prefix followed by n/p (or the window number). If swiping does nothing, it's almost always one of: an outdated daemon, moshi-hook serve not running, detection not seeing you inside tmux, or a prefix mismatch. The tmux doc has the ordered checklist.

Match your custom prefix

If you remapped your prefix (say Ctrl-A or Ctrl-X), tell Moshi so the swipe and panel send the right bytes. Set it under Settings → Shortcuts → tmux to match your ~/.tmux.conf:

# example: remap prefix to Ctrl-a
$set -g prefix C-a
$unbind C-b
$bind C-a send-prefix

Copy mode and scrollback on touch

Selecting a huge region of terminal output on iOS is miserable. For anything bigger than a line, use tmux copy mode — it scrolls and selects with the shortcut panel and Moshi's touch-tuned scrolling, and it works identically inside mosh.

If you rely on command recall, bump your shell history on the host — a phone is exactly when you want to scroll back to that command from this morning.

A phone-friendly tmux config

A few lines in ~/.tmux.conf make mobile life noticeably better:

# larger scrollback for command recall
$set -g history-limit 50000
# index windows from 1 — easier to reach on a number row
$set -g base-index 1
$setw -g pane-base-index 1
# renumber windows when one closes, so the quick-access row stays dense
$set -g renumber-windows on
# react instantly to escape (better for vim/agent TUIs)
$set -sg escape-time 10
# keep windows alive on accidental detach
$set -g destroy-unattached off

Pair tmux with hooks

tmux keeps agents alive; moshi-hook tells you when they need you. Together they're the whole point: an agent runs untouched inside a window while approvals and turn-completions reach your phone. The context Moshi reports even includes the tmux session and pane, so an inbox card knows exactly where it came from. See Hooks and the Claude Code guide.

When you don't need tmux

Short commands, quick SSH admin, a one-off shell check — fine without tmux. The rule is simple: if losing the connection mid-task would hurt, you want tmux. For agents, that's always.

Troubleshooting

Moshi doesn't detect tmux

Detection runs over a non-interactive SSH shell that often skips ~/.bashrc/~/.zshrc, so tmux in /opt/homebrew/bin or /usr/local/bin can be missing from PATH. Check what SSH actually sees and symlink or extend PATH accordingly — full steps in the tmux doc.

Swipe to switch does nothing

Walk the checklist: update moshi-hook, confirm moshi-hook serve is running, verify moshi context reports kind: "tmux", and make sure your prefix in Settings matches your config.

Where to go next

• Moshi with Claude Code — run an agent inside this workspace
• Running a fleet of agents — many windows, many agents
• Multiplexers — tmux vs Zellij vs Herdr
• Scrolling and Keyboard — touch input depth