vmux

Attention router for CLI coding-agent swarms in tmux—monitor and respond from your phone.

vmux watches your tmux panes, identifies which agent needs attention, turns
supported terminal dialogs into tappable choices, and sends your response back
through tmux. The backend and installable PWA run on your machine: no hosted
account, telemetry, or cloud control plane.

[!IMPORTANT]
vmux is a pre-release beta. macOS is used daily; Linux should work but needs
broader verification, and WSL support is not yet verified.

Requirements

• Python 3.10–3.14
• tmux
• pipx for an isolated source install

The planned PyPI distribution name is vmux-agent, but it is not published
yet. Until v0.1.0 is released, install the current source:

pipx install git+https://github.com/imitation-alpha/vmux.git

After publication, the command will become pipx install vmux-agent. The
distribution is named vmux-agent; the CLI command and Python import are both
vmux.

60-second local quickstart

Start at least one coding agent inside tmux, then run:

vmux

Open http://127.0.0.1:8787. vmux discovers agent panes automatically and
places panes needing input first. To include ordinary shell panes while testing:

vmux --include-shells

The PWA is the currently available client. Use your browser's Add to Home
Screen action for an app-like launcher. A separate native iOS companion is in
development, is not publicly available, and is not part of this repository.

Remote access

vmux sends keystrokes to processes running as you, so network access is
security-sensitive:

• Localhost is the default and safest mode.
• Tailscale is the recommended way to reach vmux remotely. Bind a reachable
  interface and always set a bearer token.
• SSH local-port forwarding is supported while vmux remains bound to
  localhost. The tunnel must run on the device that opens the browser; on a
  phone, this requires an SSH client that exposes a local forward.
• Direct LAN access requires a bearer token and should be used only on a
  trusted network.
• Public-internet access requires a bearer token and HTTPS at a correctly
  configured reverse proxy. Keep vmux's plain-HTTP listener private.

Never expose bare vmux HTTP to the public internet. WebRTC, PeerJS, signaling or
hosted relays, automatic port forwarding, and unauthenticated public exposure
are outside the supported model. See the
remote-access guide
before using a non-loopback bind.

What it does

• Discovers tmux panes and classifies Claude Code, generic agents (including
  Codex), and shells.
• Ranks needs_input, error, working, idle, and offline states.
• Parses Claude Code and conservative numbered dialogs; configurable regexes
  cover common prompts from other CLIs.
• Shows captured scrollback, extracted links, snippets, customizable allow-listed
  shortcut keys, pane stars, and connected sessions.
• Sends literal text, menu choices, or one broadcast message to multiple panes.
• Supports optional smart pane names, tokscale usage views, and an APNs backend
  for compatible companion clients.
• Vendors the PWA runtime assets; no third-party CDN is loaded.

Documentation

• Getting started
• Remote access
• Configuration
• Troubleshooting
• Architecture and client API

For a compact repository-local path, see
QUICKSTART.md.

Contributing and support

Bug fixes and objective documentation corrections may be submitted directly.
Significant features—and all networking, authentication, wire-contract, or
dependency-expanding changes—need maintainer agreement in an issue first. Read
CONTRIBUTING.md,
the Code of Conduct,
and SECURITY.md
before opening a pull request or security report.

License

MIT © imitation-alpha