Documentation

What is AgentMux#

AgentMux is a desktop application for operating AI coding agents — Claude Code, Codex, Gemini CLI, OpenCode, Aider, Cursor CLI — that execute on remote hosts and on this computer. Its core mechanism fits in one sentence:

It ships as a single binary: no server, no daemon, no account. All state is one SQLite file in the application data directory. Each remote host gets one multiplexed SSH connection — terminals, commands, and file transfers are channels on it, so ten terminals against one host is one authentication. Idle connections close after ten minutes.

Requirements#

The computer running AgentMux

Managed hosts

• Remote hosts: a POSIX shell, tmux, and an SSH account. Missing tmux is fine — the install panel can install it. Remote Windows hosts are not supported.
• This computer (Linux / macOS): just a local tmux — no sshd, no credentials.
• This computer (Windows): the same machine offers two hosts — the default WSL distribution (where tmux lives) and native Windows (PowerShell, Windows paths and toolchains, for MSVC builds, WPF, and running the .exe you just built). Native sessions persist through AgentMux's own session daemon, so closing the window doesn't stop native work either.

Optional: orchestrator and semantic search

Local orchestration and semantic memory search require Ollama plus one chat model and one embedding model. Without Ollama, everything else is fully functional.

Installation#

Each release provides one build per platform, produced by GitHub Actions from the tagged commit, with a .sha256 alongside. Builds are not yet code-signed or notarized, so the first launch takes one extra confirmation per platform.

macOS

1. Download agentmux-macos-universal.zip, unzip, and drag AgentMux.app into Applications.
2. Handle the unsigned-build prompt per your macOS version (table below).
3. After that, it opens normally.

Windows

1. Download and unzip agentmux-windows-amd64.zip — it contains agentmux.exe and an install script.
2. Double-click to run; when SmartScreen appears, choose More info → Run anyway.
3. For a proper install (to %LOCALAPPDATA%\Programs\AgentMux, with desktop and Start menu shortcuts, no administrator rights), run from the unzipped folder:

powershell -ExecutionPolicy Bypass -File install-windows.ps1

The same script with -Uninstall reverses it, without touching the data in %APPDATA%\AgentMux.

Linux

1. Install the runtime dependency first: sudo apt install libwebkit2gtk-4.1-0 on Debian/Ubuntu, sudo dnf install webkit2gtk4.1 on Fedora.
2. Download and extract agentmux-linux-amd64.tar.gz — binary, icon, .desktop entry, and install.sh.
3. Run ./install.sh, or execute the binary directly.

Verifying downloads

# every file ships with a .sha256:
shasum -a 256 -c agentmux-macos-universal.zip.sha256   # macOS
sha256sum -c agentmux-linux-amd64.tar.gz.sha256        # Linux

Quick Start#

Four steps to your first managed agent. Everything here is also reachable through the Ctrl/⌘ K command palette — the fastest route to any action.

Step 1: Add a host

A remote host needs three things:

• Address and user — the same ones you'd use with ssh user@host.
• One of three auth methods: ssh-agent (recommended — nothing to fill in), a key file (passphrase supported), or a password.
• Jump hosts (optional) for environments behind a bastion.

This computer asks for nothing but a name — no sshd, no credentials. On Windows you'll see two local hosts: the WSL distribution and native Windows. Pick per workload — Unix toolchains go to WSL; MSVC/WPF go native.

Step 2: Add a project and workspace

A workspace is a working directory on the host (usually a repository root). Two ways to add one:

• The form: pick a host, enter a path.
• The file browser (faster): browse the host's files, find the directory, and "add as project" in place — its name, path, and host are already known.

Step 3: Add an agent and start it

An agent is a name plus the command that starts it — the same command you'd type in a terminal:

# typical start commands, adjust to taste
claude                    # Claude Code
codex                     # OpenAI Codex CLI
gemini                    # Gemini CLI
aider --model sonnet      # Aider
opencode                  # OpenCode

Hit Start and it's running inside tmux on the host. Agent API keys are configured on the host side (the agent's own config or environment) — AgentMux neither reads nor proxies them.

Step 4: Attach and work

Click the agent, or search its name via Ctrl/⌘ K. What you get is a real terminal — colour, mouse, selection, search. Step in and type at any time, correct the agent's course, hand control back — no restart needed. The side panel provides Start / Stop / Restart / Attach, process state, and recent output.

The Terminal Wall#

The terminal area divides into up to nine panes (3×3), each holding its own session — on one host or several, each independently interactive:

• Add a pane: Ctrl/⌘ \. With an open tab spare it splits instantly; otherwise a dialog offers hosts, workspace directories, running agents, and open tabs.
• The layout adapts: panes divide the area in proportions, not pixels. A column too narrow to read is dropped, so a narrowed window wraps the 3×3 wall into a taller grid instead of nine slivers.
• Drag the seams to resize panes.
• Temporary zoom: double-click a pane's tab (or Ctrl/⌘ ⇧ ↵) to fill the area; again to restore. The split underneath is untouched.
• A pane is a view, not a session: closing one (Ctrl/⌘ ⇧ \) hides the terminal while the tab and its shell stay attached. The pane count is restored on next start.

Keyboard Shortcuts#

Broadcast & Receipts#

The Broadcast panel sends one instruction to any selection of agents — across projects and hosts. Unlike pasting into each terminal, every agent returns a delivery receipt telling you whether the instruction actually arrived.

• Target by project, by host, or tick agents individually.
• Per-agent delivery status; failed deliveries stand out and can be retried individually.
• Typical uses: pausing the whole fleet, issuing a new constraint ("all commit messages in English from now on"), polling progress across agents.

Host Operations#

The install panel: provisioning a new host

The install panel inspects the host first and offers only the agent CLIs and runtimes it can actually support, stating why others are unavailable. Installation runs inside tmux, so an interrupted connection cannot leave a partial package tree. tmux itself can be installed from here when missing.

Host telemetry

Per-host metrics are collected in a single command:

• CPU by mode and by core, memory, load
• Disk usage and throughput, network, file descriptors
• NVIDIA GPU utilisation where present

SFTP browser and editor

File access rides the same SSH connection. Writes are atomic and carry a modification check: if an agent working in the same directory changed the file, the save is refused rather than silently overwriting — look at what changed first, then decide.

Orchestrator & Ollama#

The orchestrator is an operations assistant driven by a local model: give it an objective (say, "work out why agent-3 stopped progressing") and it inspects fleet state, retrieves prior context, and proceeds one tool call at a time. It is disabled until you enable it.

Prerequisites

1. Install Ollama and keep it running.
2. Pull one chat model and one embedding model, for example:

ollama pull qwen3             # chat model (example — pick for your hardware)
ollama pull nomic-embed-text  # embedding model, used for semantic search

The approval flow

• Every operation that modifies a host is held for your explicit approval. The approval card shows: the tool, its full arguments, the target host, and the model's stated justification.
• Destructive operations are confirmed on every host, regardless of its trust level.
• Tools are a fixed whitelist, each carrying a risk tier fixed at declaration. Execution passes a single gate combining tier × host trust level × the run's trigger.
• Remote output enters the model marked as data; instruction-shaped text raises a flag on the approval card and in the decision log (prompt-injection defence).
• Every step of every run is recorded — including proposals refused, rejected, or left unanswered.

Scheduled patrols

The orchestrator can patrol the fleet on a schedule and report stalled agents. Scheduled runs are refused every non-read tool unconditionally — the restriction is not configurable. Patrols can find problems; acting on them always waits for you.

Skills and memory

• Skills: reusable procedures — the conditions under which one applies, the steps, the tools, the constraints — matched automatically when those conditions recur. Skills proposed by the orchestrator enter a review queue and have no effect until approved.
• Memory: project facts, stated preferences, and agent activity are indexed for retrieval by wording or by meaning. Embeddings are computed locally; nothing leaves the machine. Credentials matching known patterns are redacted before storage.

Lifecycle Semantics#

Internalise these and you'll never have a "did I just lose my task?" moment:

Building from Source#

Go 1.25+ and Node 20+. The frontend builds first (it's embedded in the binary), then Go:

git clone git@github.com:tan-zhuo/AgentMux.git
cd AgentMux
cd frontend && npm install && npm run build && cd ..
go build -o agentmux .
./agentmux

Linux needs the WebKitGTK headers and the gtk3 build tag:

sudo apt-get install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
go build -tags gtk3 -o agentmux .

Windows, for a double-clickable GUI binary with no console window:

go build -ldflags "-H windowsgui" -o agentmux.exe .

More detail (testing, cutting a release) in docs/development.md.

Troubleshooting#

macOS says the app "is damaged" or won't open

That's the normal gate for unsigned builds, not corruption. Follow the table in Installation, or fix it in one command: xattr -dr com.apple.quarantine /Applications/AgentMux.app.

Linux fails to start / missing library

Almost always the WebKitGTK runtime. Debian/Ubuntu: sudo apt install libwebkit2gtk-4.1-0; Fedora: sudo dnf install webkit2gtk4.1.

Windows: no window appears at all

GUI builds have no console for errors. Check startup-error.log in the data directory (%APPDATA%\AgentMux) — the actual failure reason is written there.

"Host key mismatch" when connecting

The host's key differs from the one pinned on first connection. Establish why first: a reinstalled host or a re-assigned IP is normal — delete the host record and re-add it. If nothing should have changed, treat it as a possible man-in-the-middle and verify the fingerprint out of band.

Status bar reports the keychain is unavailable

The encryption master key normally lives in the OS keychain (Keychain / Credential Manager / Secret Service). Where no keychain is available (common on minimal Linux desktops), AgentMux falls back to a 0600 file and says so in the status bar. Nothing breaks; to restore keychain storage on Linux, install and enable gnome-keyring or another Secret Service implementation.

The target host has no tmux

Open that host's install panel — tmux is on the list, and AgentMux installs it with the right package manager.

Orchestrator / semantic search unavailable

Check that Ollama is running (ollama list shows your models) and that both a chat model and an embedding model are pulled. Without Ollama these two features stay disabled; everything else is unaffected.

Where is my data?

All state is one SQLite file in the application data directory (%APPDATA%\AgentMux on Windows). Back up that directory to back up everything; delete it for a full reset. Credentials are stored AES-256-GCM-encrypted, with the key in the OS keychain.

Getting Help#

• File a GitHub issue — including platform, version, and startup-error.log (if any) speeds things up considerably.
• Orchestrator internals (the tool gate, trust levels, memory and skill layers) are documented in the orchestrator design doc.
• Author's blog: tanzhuo.xyz