tmux and SSH Keep Claude Code Alive — They Weren't Designed for a Phone
If you're already SSHing into a box from your phone and running Claude Code inside tmux, the hard problem is solved: the process doesn't die. What's left is everything tmux and SSH were never asked to do — and that's a real, separate list, not a complaint about either tool.
Give credit where it's due
tmux keeps a process running on the server independent of any one connection to it — close the SSH session, the claude process inside tmux keeps going, and reattaching later drops you back into the same window, scrollback and all. SSH gets you securely onto that server from a phone SSH client in the first place. Together they solve the one failure mode that actually loses work: a dropped connection killing your task outright. One practitioner's write-up of exactly this problem is worth reading directly — after losing a long-running Claude Code session to an SSH disconnect, they landed on reattaching to a terminal multiplexer as the fix, because a bare TUI process needs a real terminal underneath it and doesn't survive the connection disappearing on its own. (Reported by a user; not reproduced by us)
What neither tool ever promised
tmux shipped in 2007, SSH's protocol predates the smartphone entirely — both were designed for someone sitting at a keyboard with a mouse, not someone holding a piece of glass with two thumbs. That's not a flaw, it's just outside their scope, and it shows up in the same three places every time:
- Touch input. Ctrl, Alt, Esc, and arrow keys don't exist on a phone's software keyboard. Most SSH client apps bolt on an extra row of buttons for this, which helps, but it's still a workaround layered on top of a protocol that assumes a physical keyboard.
- Notifications. Neither tmux nor SSH has any concept of "tell me when the foreground process needs input." You either keep the app open and glance at it, or you don't find out a task finished until you happen to check.
- Network switching. Walk from WiFi to cellular, or through a dead zone, and a plain SSH connection just drops. You reconnect and reattach manually every time it happens — tmux protects the process, not the connection to it.
What people usually reach for next
| Tool | What layer it improves |
|---|---|
| mosh | The connection itself — roams across network changes and survives brief drops that would kill plain SSH, so you hit full disconnects less often |
| SSH client apps with custom key rows | Touch input for modifier and navigation keys — a UI patch on top of the terminal, not a protocol change |
| Termux (Android only) | Runs the whole toolchain locally on the phone itself — a different category, since there's no separate machine to connect to at all |
Each of these narrows the gap without closing it. mosh makes the connection sturdier, but it's still a terminal session with no concept of a push notification, and it doesn't touch the keyboard problem at all. A custom key row helps you type Ctrl-C, but it does nothing for reconnecting after a drop or knowing when Claude Code is done without looking. Termux itself is Android-only, but iOS does have local shell apps of its own: iSH runs a full Alpine Linux userland with its own package manager, and a-Shell is a native terminal with Python, Lua, vim, and a git client (lg2) built in — but they're local sandboxes, so neither one connects out to a project running on a separate development machine, which is the actual problem this article is about.
Where PocketShell differs
PocketShell approaches the same three gaps from the client side instead of patching the connection. It talks to its own agent over an encrypted WebSocket (Noise IK) rather than riding on a separate SSH client app, and instead of a connection-layer protocol like mosh recovering from packet loss mid-transport, it replays missed output at the application layer: every session keeps a per-connection sequence number and a ring buffer of recent output, so reconnecting — for any reason, WiFi to cellular included — fetches exactly what you missed since your last acknowledged position, gap detection included. On the input side there's a dedicated touch keyboard with three selectable layouts (Classic, Layered, Flick) covering the full Ctrl/Alt/Esc/arrow/function-key set a phone keyboard doesn't have, plus a separate IME buffer tab for composing a full string in the system input method before sending it as one piece. And because it wires directly into session-completion hooks for Claude Code, Codex, opencode, and Kimi CLI, it can push a notification — through Web Push or an outbound webhook, with foreground and background handled differently — the moment a task finishes or needs your input, instead of you polling the screen.
To be clear about what it doesn't change: it's not a connection-layer protocol the way mosh is — no UDP-level roaming or packet-loss recovery underneath it, just a standard WebSocket plus that application-level replay. It doesn't manage your tmux configuration either; mouse scrolling and copy-mode inside tmux itself are still whatever you've already set up. And unlike Termux, it still assumes there's a separate always-on machine somewhere running the actual agent — it isn't a way to run Claude Code entirely on the phone.
Three cases where this doesn't help
- Your computer needs to be off sometimes. PocketShell, mosh, and a custom-key-row SSH client all still need a machine that's on. If the plan is "close the laptop, keep working," that's what the official Cloud sessions are for — nothing here, including this project, changes that.
- You just want to glance at progress occasionally. If an occasional check-in is the whole use case, the official Remote Control mode already does that with no self-hosting at all, as long as your account has the right plan tier.
- You don't want to run and maintain a service. Self-hosting PocketShell means keeping a process alive and updated yourself, same as any self-hosted tool. If that tradeoff isn't one you want, staying with plain SSH plus mosh, or an official hosted option, is the more honest fit.