tmux-webui

README

tmux-webui

繁體中文 | English

tmux, on the web — and on your phone.

A web UI for tmux. One static binary on the machine where tmux runs; your panes stream to any browser — a desktop grid or an installable mobile PWA — with ANSI rendering, TUI mouse passthrough, deep scrollback, and slash/at autocomplete.

It exists for one workflow in particular: AI CLI agents running on a machine at home. Claude Code, Codex, and friends live in tmux panes on a home server. Wherever you are, whenever an idea strikes — open the PWA, hand the agent one instruction, and put the phone back in your pocket. The agent keeps working; you check in whenever you like, and a notification (or a spoken TTS summary) tells you when it's waiting on you. Supervision becomes asynchronous: no staring at a terminal while the agent thinks.

The newest piece is deck mode: an idle phone or tablet becomes a Stream Deck-style dock for your agents — live status chips for every pane, permission pills, and big context-aware buttons, so answering an agent's prompt is one tap instead of a fight with the on-screen keyboard. Beyond that: link several devices into a shared party, federate multiple hosts under one UI, and configure everything — theme, keys, thresholds — from a single JSON file.

Screenshots

Desktop panes	Mobile panes

Slash palette	Deck mode

Features

• Terminal grid — multiple tmux panes streamed side by side, ANSI-rendered, with adaptive polling. Layout presets (2×2 / 4-col / 1+2 / 3-col / single) or auto-fit to the viewport.
• TUI mouse passthrough — click, drag, and scroll inside full-screen terminal programs (lazygit, htop, yazi, less -r). Mouse events are re-encoded as SGR-1006 reports, so any mouse-aware TUI reads them natively — no per-app adaptation.
• Mobile PWA — installable to the home screen; auto-fits the pane grid to a phone screen, touch-first controls, and quick-key bars (Esc / Tab / Ctrl-C / arrows / sticky modifiers / hard-to-type shell chars) so you never fight the on-screen keyboard.
• Deep scrollback with scroll-lock — page back through history in chunks; going deep freezes live DOM updates so the view doesn't jump out from under you, then resumes auto-follow on return-to-bottom.
• Slash / at autocomplete — type / to complete Claude Code skills, commands, agents, and built-in slash commands (user-level and plugin marketplace); type @ to complete files under the focused pane's cwd. Plus user-defined bare-word shortcuts.
• Deck mode — a Stream Deck-style touch control surface: context-aware buttons, live status badges, session/window switching, permission-mode pills, and one-tap macros for driving an agentic CLI from a phone or tablet without a keyboard.
• Party / link mode — join several devices into a shared party (4-char code or QR link); when one member switches session/window/pane, the others follow. Opt-in, off by default — byte-identical to solo use when unused.
• Waiting-pane notify + TTS — an optional server-side watcher pushes a notification when an agent pane blocks on you (permission prompt, question), so a closed phone still gets alerted; in-browser TTS read-out of the same events is toggleable.
• Multi-host federation — list other hosts in config and drive their tmux sessions from one UI under a host/ prefix, with fail-soft skipping of dead hosts.
• Full UI configuration — theme (per-colour CSS overrides, font, radius), key bars, per-CLI slash palettes, scroll/history thresholds, autocomplete sources — all from one config.json. Every key is optional and defaults to historical behavior.
• Daemon mode — install as a launchd (macOS) or systemd (Linux) user service; restarts on crash, survives reboots.
• LAN mode — tmux-webui --lan binds all interfaces behind a token gate and prints a QR code to scan from your phone. See remote access.

Install

One line, any supported platform (macOS / Linux / WSL, arm64 / amd64):

curl -fsSL https://raw.githubusercontent.com/operonlab/tmux-webui/main/install.sh | sh

The installer detects your OS and architecture, offers to install tmux via your package manager if it's missing, then resolves the best install method automatically: Homebrew formula → GitHub release binary (sha256-verified) → build from source (offers a Go toolchain if needed). Native Windows gets WSL2 guidance. Useful flags:

sh install.sh --service          # also register a login service (launchd/systemd)
sh install.sh --profile          # append the bin dir to your shell profile's PATH
sh install.sh --yes              # non-interactive (CI / provisioning)
sh install.sh --method source    # force a specific method: brew|release|source
sh install.sh --bin-dir ~/bin    # custom install dir (default ~/.local/bin)

Manual alternatives: Homebrew · from source

Then run:

tmux-webui

Open http://localhost:9527 in your browser.

Use it from your phone

tmux-webui --lan

A QR code appears in the terminal. Scan it.

Requires

• tmux — brew install tmux (macOS) / sudo apt install tmux (Debian/Ubuntu)
• macOS or Linux (arm64/amd64); Windows via WSL

Configure

Everything runs on sensible defaults with zero config. To customize — theme colours, key bars, per-CLI slash palettes, scroll/history thresholds, autocomplete sources, multi-host federation — drop a ~/.config/tmux-webui/config.json. Every key is optional; omit one and it keeps its default (existing configs need no changes). Full key reference: docs/config-reference.md.

Run as a service

tmux-webui daemon install      # writes launchd plist (mac) or systemd user unit (linux)
tmux-webui daemon status
tmux-webui daemon logs
tmux-webui daemon uninstall

Update

tmux-webui update --check
tmux-webui update

Uninstall

tmux-webui uninstall -y

Removes binary, config, daemon, and uploads.

More

• Deck mode — touch control surface for Claude Code / tmux (context-aware buttons, live status, session/window switching, macros)
• Party / link mode — multi-device shared context (create a party, follow one another)
• Autocomplete coverage — what / and @ complete against
• Config reference — every config.json key
• Waiting-pane notifications — server-side push when an agent blocks on you
• Build from source
• Remote access (LAN / Tailscale / Cloudflare / ngrok)
• Daemon setup
• Homebrew install
• Dogfooding — what it means, how the maintainer runs it before tagging a release
• Cutting a release — tag, GoReleaser, Homebrew tap
• Sample dogfood config

License

MIT — see LICENSE