tmux-mobile

Control your AI agents from anywhere. Mobile-first tmux web client that lets you wrangle Claude Code, agentic workflows, and persistent terminal sessions from your phone.

Inspiration strikes unexpectedly—often when you're away from your desk. With tmux-mobile, your development environment travels with you. Access it locally or over a secure Cloudflare tunnel.

Why tmux + mobile matters now:

• Claude Code Teams and emerging agentic workflows run in tmux sessions
• Persistent sessions survive disconnects—your AI agents keep working even when you close the browser
• Zero tmux knowledge required—if you can tap a screen, you can use it
• Born from necessity—this project literally came to life on the toilet, because sometimes the best ideas (and urgent debugging) can't wait

Screenshot

Amber theme

Midnight theme

Prerequisites

• Node.js 20 or newer is required.
• tmux must be installed on the machine running tmux-mobile.
• tmux project: tmux/tmux
• Install with Homebrew (macOS):

brew install tmux

• Recommended: enable tmux mouse mode so you can switch panes by tapping in the mobile UI.

echo 'set -g mouse on' >> ~/.tmux.conf
tmux source-file ~/.tmux.conf

Quick Start

Run without cloning (recommended)

npx tmux-mobile

The CLI prints:

• Local URL: ...?token=...
• Tunnel URL: ...?token=... (when tunnel is enabled)
• Password: ... (when password auth is enabled)

Open either URL directly on your phone.

Run from source

npm install
npm start

Security Defaults

• Password authentication is enabled by default.
• If you do not provide --password, a random password is generated.
• Password is printed separately (not in URL query parameters).
• You can disable password checks for trusted local workflows with --no-require-password.
• Mobile clients attach through dedicated grouped tmux sessions, so window focus is independent per client.
• Pane focus and process/input state are still shared when two clients work in the same window/pane.
• Full security architecture, risk model, and operational guidance: SECURITY.md

Versioning

• The project intentionally stays on 0.0.x while the interface and operational behavior are still being refined.

CLI

tmux-mobile [options]

Options:
  -p, --port <port>                Local port (default: 8767)
  --password <pass>                Authentication password (optional; auto-generated by default)
  --[no-]require-password          Toggle password requirement (default: true)
  --no-tunnel                      Don't start cloudflared tunnel
  --session <name>                 Default tmux session name (default: main)
  --scrollback <lines>             Default scrollback capture lines (default: 1000)
  --debug-log <path>               Write backend debug logs to a file

Optional environment variables:

• TMUX_MOBILE_SOCKET_NAME: use a dedicated tmux socket name (tmux -L) for isolation
• TMUX_MOBILE_SOCKET_PATH: use an explicit tmux socket path (tmux -S)
• TMUX_MOBILE_DEBUG_LOG: alternative way to enable debug log file output
• TMUX_MOBILE_FORCE_SCRIPT_PTY=1: force the Unix script(1) PTY fallback

Local Development

npm run dev

Quality gate:

npm run typecheck
npm test
npm run test:e2e
npm run build

Test Harness

The automated harness avoids manual QA by validating the tmux protocol flow end-to-end:

• FakeTmuxGateway: in-memory tmux session/window/pane state machine
• FakePtyFactory: captures terminal writes/resizes and emits PTY output
• Integration tests for auth, attach flow, session picker, mutations, scrollback capture, and terminal I/O bridge
• Playwright browser tests for attach + terminal rendering, drawer behavior, and session selection regression coverage
• Optional real tmux smoke test:

npm run test:smoke

Acknowledgements

• Inspired by porterminal.
• Made with 🐶 by DagsHub.