drive your agent,
ditch the desk
Keep your creativity in hand. One command on your computer, scan a QR — and pick up your build the moment inspiration hits.
Step away from your desk and the work doesn't stop. handmux drives your real tmux panes, so the agent keeps running while you're on the train, in a queue, on the couch — pick up exactly where you left off. No app to install — open the link in your phone's browser and you're in. Works with Claude Code, Codex, aider, any shell — and it pings your phone the moment a pane needs you.
No mockup — real panes, right on your phone: say what you need and Claude Code writes the doc, it pings you when it needs you, and you review the git repo and each agent's usage — all with your thumb.
It drives any agent or TUI — and it goes furthest with Claude Code and Codex: it knows the moment a pane needs you.
Pinged when it needs you
A push the instant a pane hits a permission prompt, a plan approval, or finishes — even with the tab closed. No more babysitting a screen. One handmux hooks install wires it up.
Who's busy, who's waiting — one glance
One inbox lines up every coding agent — Claude Code, Codex — each pane tagged working · needs you · done. Tap the blocked one and you're there.
Approve with your thumb
Answer permission prompts and plan approvals right from the phone — it's driving the real keys, so a tap is a real keystroke.
One command — and it's running
Install with a single command, run it, scan the QR — about a minute later you're driving your terminal from your phone. Already have Node and tmux? There's nothing else to set up.
Zero install — with a native-app feel
No App Store, no client, no iOS lock-in — open the link in your phone's browser and Add to Home Screen. It runs full-screen as a PWA, basically a native app on iPhone or Android alike. On iPhone this is also how push works — added to your home screen, handmux can ping you the moment a pane needs you. Safari (iOS) or Chrome recommended.
One live session, two screens
Your phone drives the very tmux on your desk — not an SSH session you spun up from the phone, the same live panes. Run commands, open vim, any TUI, any agent. Step away mid-build and pick it up from your thumb, exact same state.
Agent usage, always in view
See Claude's 5-hour and weekly limit bars with reset countdowns, plus Codex's quota ring — read from local files on the host, no account login or API calls. A time marker shows whether you're burning slower or faster than the clock.
A deeply-tuned keyboard for the terminal
Typing into a terminal is the hard part on a phone — so handmux built an input system for it. Two modes fit two scenarios: command mode types straight into the terminal, with preset ESC/Tab/Ctrl+C and key combos (⌃⇧⌥ + a base key — one tap fires a real keystroke); chat mode talks to the agent in natural language. Save common commands global or per-window, reorder and edit it all in a ⚙ sheet.
A git client in your hand
Not just a diff — a VS Code-style git panel: working changes, commit history, any branch, tap for a full-screen colored diff. Multi-repo tabs, read-only, never touches your tree.
Preview your work, anywhere
Preview a static site straight from a folder — that works out of the box. Or preview a live service by port, rendered on your phone with routing, API and live reload (HMR) intact, in a phone or desktop viewport. The live-service side needs a preview domain configured once.
Docs you can read — or hear — and files both ways
Tap any path in the terminal to open it: Markdown rendered, font zoom, and read-aloud with sentence-by-sentence highlight. Move files both ways too — upload from the chat box (multi-select, path auto-filled, filtered to supported types), download with a tap, share straight in, copy any absolute path.
Reach it anywhere — direct, zero-config, or self-hosted
LAN-only by default, nothing exposed. Already have a public address? No tunnel needed — reach it directly. Otherwise handmux setup wires one: a Cloudflare quick tunnel for zero-config reach, a named Cloudflare domain, or a tunnel to your own server — the self-hosted path stays usable where Cloudflare is unreliable.
Free, open-source, no relay
handmux is fully open-source (AGPL-3.0) and free — there's nothing to pay for. It also runs no servers: many similar tools pass your session through their cloud, handmux doesn't — no cloud, no account, no middleman. Your data travels straight between your computer and your phone.
good to know
- Voice input (optional): add iFlytek credentials and chat mode turns your speech into text — fire off the next prompt hands-free.
- Update notice: handmux checks for a newer release about once an hour and lights a dot on the settings gear — a nudge to run
handmux updateon your computer. - Built for flaky networks: reconnect with backoff, a connection-lost banner, an offline page, polling that pauses when hidden — plus a reflow-safe cursor and drag-to-select copy.
- Image & GIF viewer: open any image, screenshot or GIF the terminal throws up — pinch-zoom, save to photos, share out, GIFs play inline.
- Starts at login:
handmux service installregisters launchd / systemd so the whole thing comes back after reboot. - Catch every idea the moment it strikes: a per-window idea/to-do list — jot one by voice, then drop it straight into the prompt.
handmux startOne command and it's running on your computer — LAN-only by default, nothing exposed. To reach it from anywhere, the only question is: does your machine already have a public address?
Cloud box, public IP, or a forwarded port? Then you need no tunnel at all — handmux start already listens on your machine; reach it at your own address. Add your domain + TLS in front and it's the fastest, most private path: nothing sits in between, not even Cloudflare.
No public address? Open a tunnel — pick one:
cloudflare — easiest: Cloudflare (a big CDN provider) gives your machine a public link for free, zero-config, up in seconds; its public nodes can be slow or unreliable in some regions.
cloudflare-named — same, but on your own domain — steadier.
ssh self-hosted — routes through your own server instead, not depending on Cloudflare at all.
handmux start [flags] # run it — LAN-only by default, no config needed handmux setup # configure tunnel / name / notifications (saved; re-run to change) handmux hooks install # wire Claude Code / Codex → inbox lights up + phone pings handmux stop · restart · status # control + see the live URL handmux logs [--follow] # tail the supervisor log handmux config # show effective config + where each value came from handmux update # upgrade to the latest (the app nudges you when one's out) handmux service install # start at login # flags (one-run overrides): --tunnel none|cloudflare|cloudflare-named|ssh --port --token --config
Two things on your computer — Node and tmux — and your phone needs nothing but a browser. Then one command:
npm i -g handmux # install once handmux start # run it, then scan the QR it prints — you're on your phone
That's the whole thing. Prerequisites, phone pings, tunnels, Windows/WSL2 — the full guide is in the docs →