🌐 English · 🇨🇳 中文
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 puts the same live tmux workspace from your computer in any phone or desktop browser. Keep coding with Claude Code, Codex, Pi, or any terminal tool; review changes, answer prompts, preview apps, and move files without starting a separate remote session. It is self-hosted, open-source, and needs no phone app or handmux account.
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
Your computer needs tmux and Node ≥ 22.16; the phone just needs a browser. Pick one:
Homebrew — macOS (recommended) · installs Node + tmux for you:
brew install handmux/tap/handmuxnpm — any platform · if you already have Node:
npm i -g handmuxThen run it:
handmux start # local / same-wifi, nothing exposedstart 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.
- 🧶 One workspace, everywhere. Your phone drives the real tmux panes already running on your computer—not a screenshot or a separate cloud session.
- 🔔 Stop babysitting agents. See which panes are working or waiting, get notified when you are needed, and approve from your phone.
- 🧰 A complete coding cockpit. Terminal, Agent conversations, Git, previews, docs, files, usage, and idea capture stay together.
- 🔒 Self-hosted by design. Your browser connects to your computer; handmux runs no account service or relay in between.
- Live terminal — use the same tmux pane from phone and desktop, with history, physical-keyboard input, and native copy/paste.
- Agent conversations — work with Codex in a streaming chat view; optional Claude Code and Pi integrations bring the same workspace into their supported conversation flows.
- Inbox and approvals — follow multiple panes, receive push notifications, and answer permission or plan prompts remotely.
- Git and previews — review repositories and open running sites, intranet pages, or static folders from the browser.
- Docs and files — open readable files, listen to documents, and upload, download, or share files in either direction.
- Ideas and voice — keep notes per window and dictate text through supported iFlytek or Tencent recognition modes.
- Usage at a glance — view supported Agent subscription limits and configured API-provider balances without exposing full keys to the browser.
- Resilient sessions — reconnect across weak networks and restore saved tmux workspace structure after a restart.
- Script push — send a notification to your phone from local scripts or CI with
handmux push. - Zero-install PWA — add it to your home screen for a full-screen experience in English, Chinese, Japanese, or Korean.
Codex integration is built in. Pi and Claude Code integration are optional:
handmux codex [args...]
handmux pi [args...]
handmux agent enable pi
handmux agent enable claudeSee the Agent integration guide for status, disable, compatibility, and reload behavior.
The default is a direct connection to your own computer. For access away from home or work, use a public address or a tunnel on your own Cloudflare, natapp, cpolar, or SSH setup. See the connectivity guide.
Your computer needs Node ≥ 22.16 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.
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.
📖 Docs · 🧭 Roadmap · 📝 Changelog · 🔒 Security · License AGPL-3.0
Found a security issue? Please report it privately (see SECURITY.md), not via a public issue.