muxr

Harness session multiplexer for AI coding workflows. Owns the address harness/campaign/session/segment across tmux, the filesystem, and your AI runtime, so a rename or move stays coherent in all three.

What it is

muxr is a tmux + AI runtime session manager. Sessions live as typed records on disk; tmux state and the runtime command stay in lockstep with that record. muxr save snapshots; muxr restore brings everything back.

The problem

You work across multiple projects. Each one needs its own terminal session with the right working directory and the right tool running. You open tabs, cd around, lose track of what is where. When you reboot, everything is gone.

muxr organizes tmux sessions into verticals (local directory trees) and remotes (GCE instances). Each session knows where it lives and what tool to run. muxr save snapshots everything. muxr restore brings it back.

Install

cargo install nomograph-muxr

Pre-built binaries for macOS arm64 and Linux amd64 are available in releases.

Quick start

muxr init                                # create config
muxr work                                # open the work harness switchboard
muxr work api topic-flag                 # open work/api/topic-flag campaign session
muxr switch                              # TUI picker to jump between them
muxr save                                # snapshot before reboot
muxr restore                             # bring everything back

Sessions are addressed as <harness>/<campaign>/<topic>. Topics are kebab-case and describe the work (e.g. cicd-stub-fix, retrieval-precision); they are not date-stamped. The per-harness switchboard is a singleton at <harness>/_switchboard/switchboard.

Config

One file: ~/.config/muxr/config.toml

default_tool = "claude"

[verticals.work]
dir = "~/projects/work"
color = "#7aa2f7"

[verticals.personal]
dir = "~/projects/personal"
color = "#9ece6a"

[remotes.lab]
project = "my-gce-project"
zone = "us-central1-a"
user = "deploy"
color = "#d29922"
# connect = "mosh"       # default; set to "ssh" for gcloud compute ssh
# instance_prefix = ""   # optional prefix for GCE instance names

Verticals are local directory trees. Remotes are GCE instances resolved via gcloud. Each gets a color that shows up in the TUI switcher and the tmux status bar. Remotes require the gcloud CLI.

How sessions work

muxr is a thin layer over tmux. Each session gets a named tmux session, the right working directory, and your default tool running.

muxr work api topic-flag
  tmux new-session -s "work/api/topic-flag" -c ~/projects/work
  tmux send-keys "claude" Enter
  tmux attach -t "work/api/topic-flag"

Session names follow the pattern harness/campaign/topic. The topic is mandatory and validated as kebab-case. Sessions persist across terminal restarts because tmux keeps them alive.

TUI switcher

muxr switch opens an interactive picker. Sessions are color-coded by vertical, sorted by most recent activity. Local and remote sessions appear together.

Key	Action
j / k	Navigate
Enter	Attach to session
d	Kill session (with confirmation)
/	Fuzzy filter
q	Quit

Bind it in tmux for instant access:

bind s display-popup -E -w '80%' -h '80%' "muxr switch"

Remote sessions

Remote sessions create a local tmux proxy that connects to a GCE instance and attaches to the remote tmux. The default connect method is mosh; set connect = "ssh" for gcloud compute ssh. Sessions appear in muxr ls and the switcher alongside local sessions.

muxr lab trustchain             # connect to remote, attach tmux
muxr lab ls                     # list remote sessions

Connections auto-reconnect on drops with exponential backoff.

Save and restore

muxr save                       # snapshot all sessions to JSON
muxr restore                    # recreate after reboot

Restore recreates local sessions with the correct directory and tool. Remote sessions re-establish connections.

Commands

Command	What it does
muxr	Control plane (bare shell)
muxr <harness>	Open the harness switchboard singleton
muxr <harness> <campaign> <topic>	Open or attach to a campaign session
muxr <remote> [context...]	Create or attach to a remote session
muxr switch	Interactive TUI session picker
muxr ls	List active sessions
muxr save	Snapshot session state
muxr restore	Recreate sessions after reboot
muxr kill <name>	Kill a session
muxr kill all	Kill all sessions
muxr rename <name>	Rename: tmux + session file on disk + runtime relink
muxr init	Create default config
muxr completions <shell>	Shell completions (zsh, bash, fish)
muxr tmux-status	tmux status bar integration

License

MIT

---

Part of Nomograph Labs.