amux

amux — Claude Code Multiplexer

Manage multiple Claude Code sessions from your terminal or phone. amux wraps tmux to let you run, monitor, and control headless Claude Code instances from a single dashboard — locally or over the network as a PWA.

Install

git clone <repo> && cd amux
./install.sh

Requires tmux and python3. Installs amux (and alias cc) to /usr/local/bin.

Quick Start

# Register a session
amux register myproject --dir ~/Dev/myproject --yolo

# Start it headless
amux start myproject

# Open the terminal dashboard
amux

# Or serve the web dashboard
amux serve

CLI Commands

Command Alias Description
amux   Interactive terminal dashboard
amux register <name> --dir <path> reg Register a new session
amux start <name>   Start a session headless
amux stop <name> kill Stop a running session
amux attach <name> a Attach to a session’s tmux
amux peek <name> [lines] p View session output without attaching
amux send <name> <text>   Send text/command to a session
amux exec <name> [flags] -- <prompt> run Register, start, and send a prompt in one shot
amux ls list List all sessions
amux info <name>   Show session details
amux rm <name> del Remove a session
amux start-all   Start all registered sessions
amux stop-all   Stop all running sessions
amux defaults config Manage default flags
amux serve web Start the web dashboard

Session names support prefix matching — amux attach my resolves to myproject if unambiguous.

Claude Code Flags

Pass any Claude Code flag when registering:

amux register api --dir ~/Dev/api --yolo --model sonnet
amux register fast --dir ~/Dev/fast --model haiku --dangerously-skip-permissions

Web Dashboard (PWA)

amux serve starts an HTTPS server (default port 8822) that serves a full-featured dashboard:

amux serve           # serves on :8822
amux serve 9000      # custom port

Features

Board (Kanban)

A built-in kanban board for task tracking across sessions:

# Add an item via curl
curl -sk -X POST -H 'Content-Type: application/json' \
  -d '{"title":"Fix auth bug","status":"todo","session":"myproject"}' \
  https://localhost:8822/api/board

# List all items
curl -sk https://localhost:8822/api/board

Board data is stored in ~/.amux/board.json.

Real-Time Updates (SSE)

The dashboard uses Server-Sent Events for push-based updates instead of polling:

# Test the SSE stream directly
curl -sk -N https://localhost:8822/api/events
# Outputs: data: {"type":"sessions","payload":[...]}\n\n

Offline / PWA

Install as a PWA on iOS or Android for app-like access. The dashboard is designed for offline-first use:

Background Sync is Chrome/Edge only. Safari and Firefox fall back to the existing sync banner on reconnect.

Token Stats

Click the “amux” logo to open the about modal with daily token usage:

HTTPS & Tailscale

The server auto-generates TLS certs for HTTPS, required for PWA/service worker on non-localhost. It tries in order:

  1. Tailscale — real Let’s Encrypt cert via tailscale cert, trusted everywhere with zero setup
  2. mkcert — locally-trusted CA, no browser warnings on the same machine
  3. Self-signed — fallback via openssl, requires trusting the cert manually
# With Tailscale (recommended for phone access)
amux serve
# → https://your-machine.tailnet-name.ts.net:8822

# With mkcert
brew install mkcert && mkcert -install
amux serve
# → https://localhost:8822

# Disable TLS
amux serve --no-tls

For iOS PWA without Tailscale: install the mkcert root CA (~/.local/share/mkcert/rootCA.pem) via AirDrop, then trust it in Settings > General > About > Certificate Trust Settings.

REST API

All dashboard features are backed by a REST API:

Endpoint Method Description
/api/sessions GET List all sessions with status, preview, tokens
/api/sessions POST Create a new session
/api/sessions/<name>/start POST Start a session
/api/sessions/<name>/stop POST Stop a session
/api/sessions/<name>/send POST Send text to a session
/api/sessions/<name>/keys POST Send raw tmux keys
/api/sessions/<name>/peek GET Get session output
/api/sessions/<name>/info GET Session details
/api/sessions/<name>/stats GET Token usage stats
/api/sessions/<name>/config PATCH Update config (rename, model, dir, tags, etc.)
/api/sessions/<name>/delete POST Delete a session
/api/sessions/<name>/duplicate POST Duplicate session config
/api/sessions/<name>/clone POST Clone and continue conversation
/api/sessions/<name>/clear POST Clear tmux scrollback
/api/sessions/connect POST Adopt an existing tmux session
/api/tmux-sessions GET List unregistered tmux sessions
/api/board GET List board items
/api/board POST Create a board item
/api/board/<id> PATCH Update a board item
/api/board/<id> DELETE Delete a board item
/api/board/clear-done POST Remove all done items
/api/events GET SSE stream (sessions + board)
/api/stats/daily GET Daily token stats
/api/stats/reset POST Reset token counters
/api/file GET Read file contents (for peek previews)
/api/autocomplete/dir GET Directory path autocomplete

Session Logs

amux periodically snapshots all running sessions to ~/.amux/logs/ (every 60s, up to 10MB per session). This means:

File Layout

~/.amux/
  sessions/            # session .env files (CC_DIR, CC_FLAGS, etc.)
  logs/                # session scrollback snapshots
  tls/                 # auto-generated TLS certs
  board.json           # kanban board data
  token_baseline.json  # token counter reset baseline
  defaults.env         # global default flags

Configuration

Global defaults

amux defaults show           # view current defaults
amux defaults edit           # open in $EDITOR
amux defaults reset          # clear all defaults

Set default flags applied to all sessions:

# In ~/.amux/defaults.env:
CC_DEFAULT_FLAGS="--dangerously-skip-permissions"

Per-session config

Each session is a simple env file in ~/.amux/sessions/<name>.env:

CC_DIR="/Users/you/Dev/project"
CC_FLAGS="--model sonnet --dangerously-skip-permissions"
CC_DESC="Main backend work"
CC_TAGS="backend,api"
CC_PINNED="1"

Architecture

Everything lives in a single file: amux-server.py. The Python server uses http.server.ThreadingHTTPServer with inline HTML/CSS/JS for the dashboard. No build step, no dependencies beyond Python 3 and tmux.