handmux

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.

📖 Docs · 🧭 Roadmap · 📝 Changelog · 📦 npm

Quick start · about a minute

Your computer needs tmux and Node ≥ 18; 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 (experimental) — read and drive a Claude session as a chat instead of a terminal: bubbles with Markdown, tool cards with colored diffs, question cards you answer with a tap, warm colour tones. Experimental — may be unstable: enable it in Settings → 启用对话视图 / Enable chat view, then switch views from the window bar.
• Real-time terminal + desktop physical keyboard input — terminal output streams as it happens on both phone and desktop. Scrolling up immediately browses recent tmux history without losing your place, pauses the stream when needed, and loads older history as you continue; returning to the bottom resynchronizes the live screen. When the source pane is shorter than the browser, spare rows show recent history above a faint dashed live boundary instead of empty space. Leaving the page pauses delivery; after 10 seconds away, returning starts from a fresh current screen instead of replaying stale output. Live pushing uses WebSocket, automatically falls back to snapshot pulling on a poor connection, and returns after 30 stable seconds. One top-right tag combines the actual mode and current latency; click it to see connection quality, the configured mode, fallback reason and retry countdown. Settings can keep this browser on snapshot pulling at an active interval from 0.8 to 2 seconds. On desktop, type into the current pane immediately without tapping “Show keyboard”; terminal-page keys keep working even after focus lands on the Window toolbar. Shift+Enter or the draft field opens draft mode with shortcuts, upload, history, voice and multiline editing intact. Enter sends and stays in draft mode, Shift+Enter inserts a newline, and IME Enter only confirms composition; press Esc or click the terminal to return to direct input. When a dialog, sheet, or menu is open, Esc closes only the top layer, one layer per press. Settings subpages stay stacked above Settings, so Back or Esc returns there before the main screen. Drag to select text, then copy/paste with Cmd+C / Cmd+V on macOS or Ctrl+Shift+C / Ctrl+V (or Ctrl+Shift+V) on Windows/Linux; Ctrl+C remains the terminal interrupt. Settings → Keyboard mode can auto-detect or force Mobile/Desktop for this browser only. Browser-reserved shortcuts such as Cmd+W/T/L/R, F5, and F12 stay with the browser.
• Command & chat modes — one bottom bar, two modes: type straight into the terminal, or talk to the agent in natural language. Both default quick bars include Ctrl+C. handmux shortcuts configures shared key/text items; each phone's ⚙ editor shows the effective quick-bar order, interleaves shared and local items, and can remove a shared item from that device only with immediate undo. Adding a phone-local item confirms success and returns directly to the list. Server changes apply live and phones reload them on foreground—no restart or polling required.
• 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 silently keeps the metadata needed to rebuild your latest tmux workspace. After a computer or tmux-server restart, restore it beside any new sessions from the phone or with handmux restore; existing sessions are never replaced.
• Git viewer — changes / commit history / any branch / full-screen colored diff, multi-repo tabs, read-only, never touches your tree.
• Site preview — a static folder, or a running HTTP/HTTPS service by port (routing / APIs / live-reload intact), in a phone or desktop viewport. Set its bare preview domain once in handmux setup.
• Docs — tap a path in the terminal to open it; Markdown rendered, font zoom, sentence-by-sentence read-aloud.
• 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 in the browser; add to home screen for full-screen. Multilingual — English, 简体 / 繁體中文, 日本語, 한국어.

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