handmux

🌐 English  ·  🇨🇳 中文

handmux.com

One phone, a whole mobile vibe-coding cockpit. Built on tmux — one command on your computer, scan a QR, and your live session, Claude Code, Codex, git, previews and docs are all in your hand, creativity ready wherever you are.

handmux is more than a terminal on your phone. It puts the same live tmux session running on your computer into your phone's browser (real panes, not a read-only mirror), then builds a whole mobile vibe-coding cockpit around it: Claude Code / Codex push you the moment a pane needs a decision — approve with your thumb, or fire off a new instruction by voice; browse a full-screen colored git diff; preview a running site in one tap; hear a doc read aloud line by line; move files both ways. Nothing to install on the phone — open a link and you're in; "Add to Home Screen" and it runs full-screen as a PWA, basically a native app. Curl up on the couch or squeeze onto the train — the vibe coding never stops, your creativity stays in hand.

  
Real phone browser, real panes — say what you need and Claude Code writes it, then tap a filename to preview (left); a push pings you when needed, and you review the git repo & each agent's usage (right).

📖 Docs · 🧭 Roadmap · 📝 Changelog · 📦 npm

Quick start · about a minute

Your computer needs tmux and Node ≥ 20; the phone just needs a browser. Pick one:

Homebrew — macOS (recommended) · installs Node + tmux for you:

brew install handmux/tap/handmux

npm — any platform · if you already have Node:

npm i -g handmux

Then run it:

handmux start        # local / same-wifi, nothing exposed

start prints a QR code (plus a URL and token). Scan it with your phone — the token rides in the code, so you're signed in on first open. You'll see your real tmux session; tap one and start driving.

Want to reach it from anywhere? Add one flag for a free public HTTPS link:

handmux start --tunnel cloudflare   # instant public URL (cloudflared auto-installed)

Tunnel types, self-hosting, Windows/WSL2, and the full command & flag reference → see the docs.

Why handmux

• 🧰 More than a terminal — a whole mobile vibe-coding cockpit in your pocket. Full-screen colored git diffs, one-tap preview of a running site, docs read aloud line by line, files moved both ways — a whole dev kit in hand, no hopping between apps.
• 🚀 One minute from zero to coding on your phone. One handmux start, one scan, done — no sign-up, no App Store, no app to sideload; just a link. "Add to Home Screen" and it's a full-screen PWA, as smooth as a native app.
• 🧶 Walk away, keep working. Your phone drives the one live tmux pane on your desk (not a new shell, not a screenshot). Close the laptop and keep watching from your thumb — exact same state.
• 🔔 When it needs you, your phone rings. Claude Code / Codex push the moment they need a decision; add it to your home screen and they come through as system notifications. An inbox tags each pane working / needs-you / done — many projects at a glance — and you approve permissions and plans with a tap, so you stop babysitting the screen.
• 🔒 Your code goes through no middleman. Free and fully open-source; we run no server in the middle — your data travels straight between your computer and your phone, so it stays secure.

Features

• Claude Code / Codex, deeply — an inbox status ledger, thumb-approve permissions & plans, and stable host-wide usage bars shared by every connected device.
• Chat view — drive Codex CLI through App Server with streaming Markdown bubbles, tool cards, native Goal lifecycle cards, and session status; setting or restarting a Goal creates a fresh active native Goal, immediately shows its user-side card on the right, and starts Codex's built-in continuation. An active or paused Goal stays beneath the live read-only turn task list, Codex terminal feedback stays with its originating turn on the left, and every entry opens the same Bottom Sheet. The current Goal uses one equal-width iOS-style action row; clearing it removes the resident Goal and closes the sheet, while its historical chat card remains. The current terminal Goal can be edited before restarting. Long replies hold at their beginning for reading, with an explicit jump back to the latest output. Existing panes can switch in place, and messages sent during a turn form an editable server queue. The queue and delivery receipts survive Handmux restarts, and uncertain sends are reconciled before retrying. Claude Code chat is an independently enabled experimental option.
• Real-time terminal + desktop keyboard — stream the same tmux pane on phone and desktop with scrollback, weak-network fallback, direct physical-keyboard input, and native copy/paste.
• Command & chat modes — switch between direct terminal input and natural-language agent chat, with direct Alt and Space keys on the mobile command keyboard and a customizable quick bar that stays in sync across devices.
• Client reload after updates — once the server update has finished, use Settings → Reload app to load the new client without quitting and reopening the home-screen app.
• Script push — notify your phone from any script or CI step with handmux push; target all devices, a named session, or a specific device.
• Workspace recovery — handmux keeps the metadata needed to restore your latest tmux workspace after a computer or tmux-server restart, without replacing existing sessions.
• Git viewer — changes / commit history / any branch / full-screen colored diff, multi-repo tabs, read-only, never touches your tree.
• Web Preview for URLs and static folders — preview URLs by phone or computer proxy, or open an isolated static folder, with narrow/wide page widths and zoom; computer proxy can also request a mobile or desktop site version. It embeds pages rather than replacing a full browser.
• Docs — tap recognized text-file paths in the terminal to open them, regardless of extension; ordinary slash-separated prose stays plain. Markdown rendered, font zoom, sentence-by-sentence read-aloud. Binary files stay download-only.
• Mobile select & copy — long-press to select in the terminal, drag iOS-style handles to fine-tune, copy the selection / a whole line / a whole paragraph.
• Files both ways — multi-select upload from the chat box, download, share in, copy any absolute path.
• Ideas — catch every one — a thought the moment it strikes: a per-window idea/to-do list, jot one by voice and drop it straight into the prompt.
• Built for flaky networks — backoff reconnect, connection-lost banner, offline page, polling that pauses in the background; a reflow-safe cursor.
• Zero-install PWA — runs full-screen from your home screen, with English, 简体 / 繁體中文, 日本語, and 한국어.

Workspace recovery

handmux continuously maintains two redundant copies of the latest workspace metadata. They are not browsing history: ordinary changes and deletions handmux can confirm simply update the current state. A selectable checkpoint is archived only when the computer or tmux environment changes. If the final tmux session disappears outside handmux, tmux cannot distinguish an intentional deletion from a crash, so handmux retains the last state and can offer recovery immediately, without waiting for a new tmux server or session. Every checkpoint from the latest 24 hours is kept; older history is then trimmed to the newest 10, while the latest valid checkpoint never expires just because of age.

After such a restart, the phone shows Restore last workspace for one hour when a checkpoint has work left to restore; if tmux has no sessions it opens the confirmation directly. Choosing Ignore this backup suppresses that checkpoint only on that phone; an ordinary close does not. When recovery finishes, the phone reports the actual sessions, windows, and panes restored, but does not automatically open or bind them; choose Bind restored sessions if you want them on that phone. The CLI remains available after the phone prompt expires:

handmux restore --dry-run                         # preview the latest plan
handmux restore                                  # restore; TTY picker, otherwise latest
handmux restore --list                           # list retained checkpoints
handmux restore --checkpoint <id> --session api  # select history / restore one session

Restore is additive and idempotent. It never stops, renames, replaces, or changes the topology of a current session; a name collision becomes name-restored, then name-restored-2. Windows, panes, working directories and layouts are rebuilt where safe. Only verified Claude Code/Codex sessions are resumed from their persisted session IDs; ordinary panes reopen as shells in their saved directories, without replaying commands or scrollback. Metadata lives under ~/.handmux/workspaces/; it can include paths, tmux names/layout and agent session IDs, but not pane output.

Script push

Send a push notification to your phone from any script, CI step, or build hook:

handmux push "Build done" "Took 3m12s"

Runs on your computer against the already-running handmux server (loopback + local server token — no config, no remote endpoint). Web Push must be enabled first (handmux setup).

Syntax

handmux push <title> <body> [options]

Scopes — pick at most one:

• (default) — all subscribed devices
• --session — only devices subscribed to the named session(s)
• --device — only the specified device(s) by key

--session and --device are mutually exclusive.

The device key is shown in the phone app under Settings → Script push. It is an addressing identifier, not a secret — the security boundary is the local server token.

Reliability: Web Push is best-effort. For delivery-critical alerts use a dedicated messaging app (WeChat, Slack, etc.).

Networking: one decision

No tunnel by default — the phone connects straight to your own computer, nothing exposed and no middleman. To reach it from outside, just ask: does your machine already have a public address?

• Yes (cloud box / public IP / forwarded port) — no tunnel needed, connect directly; fastest and most private.
• No — open a tunnel. Each runs on your own free third-party account — handmux just wires it up and operates no relay of its own: cloudflare (zero-config, up in seconds, but its public edge can be slow or unreliable in some regions) · cloudflare-named (your own domain, steadier) · natapp / cpolar (domestic providers that stay reachable inside mainland China) · ssh self-hosted (through your own server).

Tunnel config, Web Preview, autostart, and voice/push credentials → see the docs.

Once autostart is installed, handmux start / stop / restart coordinate with that same launchd/systemd service (including after an upgrade). A lifecycle lock prevents concurrent launches; status shows the running version and warns with PIDs if stale/duplicate supervisors exist, while stop reaps every copy.

Requirements

Your computer needs Node ≥ 20 and tmux ≥ 3.0; the phone just needs a browser. On Windows, run it inside WSL2 (a real Linux kernel + real tmux) — see the docs.

Feedback & community

Hit a bug, or wish handmux did something? Open an issue — that's the channel that actually gets tracked (Chinese or English both welcome). Users in China can also join the WeChat user group.

More

📖 Docs · 🧭 Roadmap · 📝 Changelog · 🔒 Security · License AGPL-3.0

Found a security issue? Please report it privately (see SECURITY.md), not via a public issue.