Skip to content

Get started

tmux-rc runs on the machine where your tmux sessions live. Open its web app on your desktop or phone to see what your agents are doing and answer them through chat or direct dashboard controls.

Try it without a model account

Install tmux, Python 3.12 or newer, and uv . Keep an existing tmux session running, or start one and launch your preferred agent. Then run:

TMUXRC_NO_LLM=1 uvx --from "git+https://github.com/querystory/tmux-rc.git" tmux-rc

Open http://127.0.0.1:18030/m on that machine. This mode uses heuristics for basic activity and prompt detection; richer summaries require the model pass.

Enable summaries

The default classifier uses Gemini through Vertex AI. Configure a Google Cloud project and durable credentials as described in Vertex authentication . For an installed service, supply these environment variables:

GOOGLE_CLOUD_PROJECT=your-project \
GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json \
  uvx --from "git+https://github.com/querystory/tmux-rc.git" tmux-rc

Pane content is sent to the classifier provider. Classification calls are metered; the dashboard reports usage. TMUXRC_NO_LLM=1 disables that pass.

For configuration, service installation, and development from a checkout, see the repository README .

Connect your phone

The daemon binds to loopback and has no built-in login, so run it only on a machine you alone use: every other account on the host can reach a loopback port. Put an authenticating front end in front of it before making it reachable remotely. Follow the remote access guides for Tailscale, Cloudflare Tunnel with Access, and other options.

On iPhone, follow iPhone setup to install the PWA, enable push notifications, and configure Live Mode. Agent setup covers optional agent settings that improve the dashboard’s observations.

Move to another machine

tmux-rc export writes one .tgz with everything another machine needs: the history database (pane history, plan usage, and the tmux layout, which the new machine then offers back as a workspace to restore), accounts, mocks, scratch pages, and every ~/.claude* and ~/.codex* dir, so agents can resume their conversations. It runs while the daemon does. On the new machine, clone the checkout, then:

  1. Copy the archive over, stop tmux-rc there if it runs (systemctl --user stop tmux-rc), and quit every Claude and Codex session there: a running agent rewrites ~/.claude.json and its settings from memory, over what the import put there. The import warns if it sees one.
  2. uv run tmux-rc import tmux-rc-export-<host>-<date>.tgz. Whatever it replaces is kept beside it as *.pre-import-<time>, and paths under the old $HOME are rewritten. If it fails part way, it puts back everything it had replaced.
  3. make install-units, and make docs if you serve the docs.

Import only an archive you made yourself: it holds agents’ hooks and settings, which run code on the machine that imports them.

Logins stay out unless asked for: the agents’ logins, ~/.claude.json, the push keys, ~/.config/tmux-rc and the checkout’s .env. Without them, sign in again on the new machine. Only those are kept out: agents’ settings (an env block, an apiKeyHelper, Codex’s MCP servers’ tokens), their conversations and the history database go in by default and may still hold keys, so treat every archive as private. --with-secrets adds the logins, and the file then holds every sign-in and key: move it in one pipe that never leaves a file behind, uv run tmux-rc export --with-secrets -o - | ssh newhost 'cd tmux-rc && uv run tmux-rc import -'. --no-scratch and --no-agents make the archive smaller.

Settings › Export all… makes the same archive from the app: tick the parts to include, each shown with its size before compression, and download.

What this website serves

This is the public project website and documentation. Your live dashboard and terminal controls are served by your own daemon at /m; no running agent sessions are hosted here.