handmux
A mobile vibe-coding cockpit — built on tmux: drive your live session, Claude Code / Codex — anything a terminal can run — from your phone. 移动 Vibe Coding 驾
What is handmux?
A mobile vibe-coding cockpit — built on tmux: drive your live session, Claude Code / Codex — anything a terminal can run — from your phone. 移动 Vibe Coding 驾驶舱 —— 基于 tmux 实现,可在手机上驱动你的会话、Claude Code / Codex、任何终端能实现的东西。
Overview of handmux
What it is
handmux is a self-hosted, open-source tool that turns your phone into a mobile vibe-coding cockpit. Built on tmux, it lets you drive your live terminal session, Claude Code, Codex, or any command-line tool from your phone's browser. No phone app or handmux account is required; your browser connects directly to your computer.
Key features
- 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.
Use cases
Use handmux to continue coding with Claude Code, Codex, Pi, or any terminal tool from your phone while away from your computer. Review changes, answer agent prompts, preview apps, and move files without starting a separate remote session. It is designed for developers who want to stay productive on the go with a live tmux workspace.
Getting started
Your computer needs tmux and Node ≥ 22.16; the phone just needs a browser. Pick one:Homebrew — macOS (recommended) · installs Node + tmux for you:bashbrew install handmux/tap/handmuxnpm — any platform · if you already have Node:bashnpm i -g handmuxThen run it:bashhandmux 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:bashhandmux start --tunnel cloudflare # instant public URL (cloudflared auto-installed)```
License and pricing
License: AGPL-3.0. Pricing type: open source.
Based on the project's public README and repository metadata.