muster

Scale your agent sessions with Claude Code and others, use them across multiple machines, and use them easily from your phone with your voice and one hand.

Self-hosted: one Go server and Postgres, in Docker on one of your machines, reached over HTTPS on your private Tailscale network and nowhere else. The UI installs on your phone as a PWA. Your other machines dial out to it.

Not to be confused with two other apps called Muster: the Mac menu-bar app (agentmuster.app) and the desktop app for running parallel agents in git worktrees (musterup.dev). This muster is the self-hosted one, for your phone and every machine you run agents on. How it compares with Happy, Claude Code Remote Control and SSH + tmux: docs/comparison.md.

How it works

muster shows your own sessions: a coding agent you started in tmux on one of your machines is a mirrored session, and a message from your phone is typed into that same session, so it is all there when you are back at the keyboard. muster sees only sessions inside tmux. It can also start dispatched agents, separate sessions in Kubernetes pods; that is opt-in, and the one-prompt install below sets up mirrored sessions only. A Claude Code session opens in the Rendered view, a chat; the Terminal view is the fallback, and a window that has only the Terminal view says why. The details, and how to bring a session you already have into tmux: docs/mirroring.md.

Why muster

• Run more sessions without losing track of them. Every tmux window on every machine becomes a card, newest activity first. A bar at the bottom of the screen switches between sessions in one tap, and its search finds one by codename, title, repository or kind as you type.
• Every machine, nothing exposed. A small host agent, muster-mirror, runs on each machine as a user service and opens an outbound tunnel to your muster server. Your laptop, workstation and build box show up side by side. They dial out, and muster opens no network port on them (the optional MCP endpoint listens on loopback only). The server itself is reached only through your tailnet.
• Your phone, your voice, one hand. muster is designed for a phone first: join your tailnet with the Tailscale app, scan the QR code muster doctor can print, and install muster to the home screen. The controls sit at the bottom of the screen, within reach of your thumb. Tap the mic, speak, and the transcript lands in the message box. You read it, then press Send. Notifications tell you when something is waiting on you.
• Agent-agnostic. Start any coding agent in tmux (Claude Code, Codex, opencode, Gemini CLI) and it appears as a card. Claude Code sessions render as a chat; opencode and Hermes sessions have their own read views; anything else, Codex and plain shells included, is a live terminal.

Quickstart

You need:

• a Tailscale account with MagicDNS and HTTPS certificates on, and Tailscale on every machine and on your phone;
• on the machine that will run the server: Docker with Compose v2, and about 10 GB of free disk (20 GB with local dictation);
• tmux on every machine. Linux or macOS, amd64 or arm64. macOS hosts are experimental: there, only a Claude Code window whose Rendered view resolves can be viewed. The Terminal view cannot attach on macOS yet (internal/mirrorhost/pty_other.go), so shells, Codex and any window without a Rendered view cannot be viewed, and Rendered-view detection is unverified on a real Mac.

(a) Let your agent install it. Paste this one prompt into the coding agent (Claude Code, Codex, opencode, Gemini CLI, …) on each machine you want in muster. The first paste sets up the server; on each further machine, tell the agent muster already runs, and that machine joins it:

Set up muster for me: read https://raw.githubusercontent.com/ZacxDev/muster/main/INSTALL.md and follow it step by step. Ask me everything you need in one go up front, then do the rest yourself.

It asks its questions once, up front (other machines, how dictation should work, whether muster may type into each machine's terminals), then:

• runs the server in Docker, behind tailscale serve on your tailnet;
• connects each machine's tmux sessions with muster-mirror;
• finishes with muster doctor, which checks every part end to end, says how to fix what fails, and (with qrencode installed) prints a QR code of the address for your phone.

While there is no session yet, home shows how to start an agent in tmux (tmux new -A -s work claude) and the same prompt, to connect another machine. More in docs/onboarding.md.

(b) Install it yourself. INSTALL.md is the same guide, step by step.

Install from inside Claude Code

The one prompt above is the main path. In Claude Code you can instead add this repository as a plugin marketplace and install the muster plugin:

/plugin marketplace add ZacxDev/muster
/plugin install muster@muster

Then ask Claude Code to "set up muster". The plugin holds one skill, muster-setup, which follows the same INSTALL.md from its URL, so it never carries a copy of the steps. Agents that use the skills CLI can install the same skill with npx skills add ZacxDev/muster.

To hack on muster, docs/development.md runs it from source against a throwaway database.

Features

Core

• Mirrored sessions. Each tmux window on your machines is shown live. A Claude Code window renders as a chat, and the Terminal view is one tap away (on a Linux host; on a macOS host there is no Terminal view yet, see Requirements). Viewing a window never moves your own terminal. → docs/mirroring.md

• Session switcher, sidebar and search. A bottom bar with Recent, Waiting, Pins and All (and a pin button for the session you are on), and a sidebar that lists every session like channels in a chat app: the chief first (if you turned one on), then the sessions waiting on you, then the rest by recency, the long-idle ones folded under Idle. The search opens with the magnifier on the bar or in the sidebar, or /, and finds a session by its codename, title, repository, kind or machine. Home opens the chief's chat, or the session you opened last. → docs/mirroring.md

• Agent actions. A dispatched agent's page shows its live status and has a ⋯ menu to rename, start, stop or delete it; the + beside Agents in the sidebar dispatches a new one (or saves it for later). → docs/provisioner.md

• Message box and step-up. Send text into a Claude Code session, a plain terminal pane (Codex, Gemini CLI, a shell) or a dispatched agent. The message box does not send to opencode yet, and sends to Hermes only through the host's gated -hermes-send; type into either from the Terminal view. Typing into a mirrored session needs a recent sign-in: you confirm your password again (or a passkey, with per-user accounts). → docs/sending-and-step-up.md

• Dictation. A mic on every message box, transcribed by a speech-to-text service you choose: the installer offers a local model on the server (GPU or CPU) or your own OpenAI-compatible API key. The transcript is never sent by itself. → docs/dictation.md

• Push and PWA. Web Push notifications, plus an installable app with a share target, shortcuts and a badge. → docs/push.md

• Asks. A single queue of everything waiting on you. An agent can ask you a question and wait for your answer instead of stopping. → docs/attention.md

  

• Context badges. Each tool call in a Claude Code session shows how much context it added. → docs/mirroring.md

• Task board. Tasks have statuses, comments, attachments, tags and a review queue. People and agents share the board. → docs/tasks.md

Advanced / optional

These are optional, and most are off until you configure them.

• Agent dispatch on Kubernetes. Start an agent on a task in its own pod. → docs/provisioner.md
• Chief (off by default). An optional agent that reports on and manages the rest of the fleet. It runs in its own Kubernetes pod, so it needs the agent provisioner. Turn it on or off under Account → Chief. While it is on, home opens its chat and the sidebar lists it first; off (the default for a new install or user), home opens the session you opened last and nothing is sent to it. → docs/chief.md
• Connectors. Agents use your stored HTTP credentials through muster's proxy, and never see the secret. → docs/connectors.md
• Browser flows. A queue of scripted browser jobs, run by a runner you host, each approved by its owner. → docs/browser-flows.md
• Memo relay. Delivers cairn memos to dispatched agents. → docs/memo-relay.md
• GitHub App. muster's own GitHub identity, and tokens scoped to one repository for agents. → docs/github-app.md
• File attachments. Attach files in the message box. They are stored in S3-compatible storage. → docs/uploads.md
• Accounts. Per-user accounts through GoTrue, with passkeys, invites, roles and API tokens, kept apart by row-level security. → docs/auth.md
• CLI. muster, a client for agents and scripts. → docs/cli.md

Architecture

flowchart LR
  browser["Phone / browser (PWA)"] -->|HTTPS| server["muster-server"]
  cli["muster CLI · agents · scripts"] -->|JSON API + tokens| server
  server --> pg[("Postgres<br/>(row-level security)")]
  host["muster-mirror<br/>on each of your machines<br/>(tmux, Claude Code, …)"] -->|"outbound WebSocket tunnel"| server
  server -.->|optional| stt["speech-to-text"]
  server -.->|optional| push["Web Push"]
  server -.->|"optional"| k8s["Kubernetes<br/>agent pods"]

Loading

docs/architecture.md covers the binaries, the listeners, and what each component trusts. The full documentation index is docs/README.md.

Status and limits

• Run one replica. Some background loops and the mirror tunnel keep their state in memory.
• An interactive mirror is a shell on that host. Anyone who can type into that host's Terminal view (after a recent sign-in) can run commands as the user muster-mirror runs as.
• Agent dispatch is opt-in and only lightly proven. The repository ships no Kubernetes manifests.

The full list is in docs/limits.md.

Licence

MIT. See LICENSE.

To muster is to assemble a force for duty. A muster roll is the register of who is present and what each is assigned.