Skip to content

mixpeek/amux

BranchesTags

Repository files navigation

amux — The Agent Control Plane

Open-source control plane for AI agents. Run dozens of parallel agent sessions from your browser or phone — with a web dashboard, kanban board, notes, CRM, email, browser automation, slash-command skills, and agent-to-agent orchestration. Self-healing, single-file, zero external dependencies. Currently supports Claude Code via tmux.

amux.io · Getting started · FAQ · Blog

git clone https://github.com/mixpeek/amux && cd amux && ./install.sh
amux register myproject --dir ~/Dev/myproject --yolo
amux start myproject
amux serve   # → https://localhost:8822

License: MIT + Commons Clause — free to use, modify, and self-host. Commercial resale requires a separate license.

Why amux?

Problem amux's solution
Claude Code crashes at 3am from context compaction Self-healing watchdog — auto-compacts, restarts, replays last message
Can't monitor 10+ sessions from one place Web dashboard — live status, token spend, peek into any session
Agents duplicate work on the same task Kanban board with atomic task claiming (SQLite CAS)
No way to manage agents from your phone Mobile PWA + native iOS app — works anywhere, offline support
Agents can't coordinate with each other REST API orchestration — send messages, peek output, claim tasks between sessions
Agents operate in a vacuum — no shared context Channels — 1:1 inter-session chat with @mentions so agents can coordinate in real time
No persistent knowledge between sessions Notes — markdown documents agents can read, write, and reference across sessions
No way to automate recurring work Scheduler — named cron-style recurring jobs with built-in management UI

Key Features

Agent infrastructure

  • Self-healing — auto-compacts context, restarts on corruption, unblocks stuck prompts. Learn more →
  • Parallel agents — run dozens of sessions, each with a UUID that survives stop/start
  • Agent orchestration — agents discover peers and delegate work via REST API + shared global memory. Learn more →
  • Channels — 1:1 inter-session messaging with @mentions so agents can chat, delegate, and coordinate in real time
  • Kanban board — SQLite-backed with auto-generated keys, atomic claiming, custom columns, iCal sync
  • Conversation fork — clone session history to new sessions on separate branches
  • Git conflict detection — warns when agents share a dir + branch, one-click isolation
  • Token tracking — per-session daily spend with cache reads broken out

Dashboard & mobile

  • Web dashboard — session cards, live terminal peek, file explorer with markdown editor, search across all output. Learn more →
  • Mobile PWA — installable on iOS/Android, Background Sync replays commands on reconnect. Learn more →
  • Native iOS app — available on the App Store

Built-in tools

  • Notes — full markdown notes system with rich editor, find-in-page, and inter-session sharing
  • CRM — contacts, companies, interaction logs, follow-up tracking, and tags
  • Email — send and read email through the Mail.app API integration
  • Browser automation — shared Playwright instance with saved auth profiles, screenshots, and an AI agent mode
  • Skills / slash commands — project-level custom commands (e.g. /commit, /review-pr) that agents can invoke
  • Scheduler — named recurring jobs with cron expressions and a management UI
  • File explorer — browse agent working directories, preview files, edit markdown with in-page search

Architecture

  • Single file — one Python file with inline HTML/CSS/JS. Edit it; it restarts on save. Learn more →

How It Works

Status Detection

Parses ANSI-stripped tmux output — no hooks, no patches, no modifications to Claude Code.

Self-Healing Watchdog

Condition Action
Context < 50% Sends /compact (5-min cooldown)
redacted_thinking … cannot be modified Restarts + replays last message
Stuck waiting + CC_AUTO_CONTINUE=1 Auto-responds based on prompt type
YOLO session + safety prompt Auto-answers (never fires on model questions)

Agent-to-Agent Orchestration

# Send a task to another session
curl -sk -X POST -H 'Content-Type: application/json' \
  -d '{"text":"implement the login endpoint and report back"}' \
  $AMUX_URL/api/sessions/worker-1/send

# Atomically claim a board item
curl -sk -X POST $AMUX_URL/api/board/PROJ-5/claim

# Watch another session's output
curl -sk "$AMUX_URL/api/sessions/worker-1/peek?lines=50" | \
  python3 -c "import json,sys; print(json.load(sys.stdin).get('output',''))"

Agents get the full API reference in their global memory, so plain-English orchestration just works.

Web Dashboard

  • Session cards — live status (working / needs input / idle), token stats, quick-action chips
  • Peek mode — full scrollback with search, file previews, and a send bar
  • Workspace — full-screen tiled layout to watch multiple agents side by side
  • Board — kanban backed by SQLite, with atomic task claiming, iCal sync, and custom columns
  • Notes — markdown documents with rich Quill editor, find-in-page, and inter-session sharing
  • CRM — contacts with company, role, email, phone, LinkedIn, interaction history, and follow-up tracking
  • Channels — 1:1 inter-session chat with @mentions for real-time agent coordination
  • Files — browse and edit files in any session's working directory, with syntax highlighting and in-page search
  • Scheduler — create, edit, and monitor recurring cron-style agent jobs
  • Reports — pluggable spend dashboards pulling from vendor billing APIs

CLI

amux register <name> --dir <path> [--yolo] [--model sonnet]
amux start <name>
amux stop <name>
amux attach <name>          # attach to tmux
amux peek <name>            # view output without attaching
amux send <name> <text>     # send text to a session
amux exec <name> -- <prompt> # register + start + send in one shot
amux ls                     # list sessions
amux serve                  # start web dashboard

# Board
amux board add "task title"  # create a board item
amux board doing PROJ-1      # mark in progress
amux board done PROJ-1       # mark done

# CRM
amux crm add "Name" company=X email=Y role=Z
amux crm list               # list contacts
amux crm log PPL-1 "met at conference"
amux crm fu                 # show pending follow-ups

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

Install

Requires tmux and python3.

git clone https://github.com/mixpeek/amux && cd amux
./install.sh   # installs amux to /usr/local/bin

HTTPS

Auto-generates TLS in order: Tailscale cert → mkcert → self-signed fallback. For phone access, Tailscale is the easiest path. Remote access guide →

Trusting the certificate on your phone

The PWA uses a service worker for offline support — managing sessions, checking the board, and sending messages all work without a connection. For the service worker to register, your phone's browser must trust the HTTPS certificate. If you're using mkcert, your phone won't trust the CA by default. Serve it over HTTP so your phone can download and install it:

python3 -c "
import http.server, os, socketserver
CA = os.path.expanduser('~/Library/Application Support/mkcert/rootCA.pem')
class H(http.server.BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == '/':
            self.send_response(200); self.send_header('Content-Type','text/html'); self.end_headers()
            self.wfile.write(b'<a href=\"/rootCA.pem\">Download CA cert</a>')
        elif self.path == '/rootCA.pem':
            data = open(CA,'rb').read()
            self.send_response(200); self.send_header('Content-Type','application/x-pem-file')
            self.send_header('Content-Disposition','attachment; filename=\"rootCA.pem\"')
            self.send_header('Content-Length',len(data)); self.end_headers(); self.wfile.write(data)
socketserver.TCPServer.allow_reuse_address = True
http.server.HTTPServer(('0.0.0.0', 8888), H).serve_forever()
"

Then open http://<your-ip>:8888 on your phone (use your Tailscale IP if on Tailscale, or LAN IP if on the same Wi-Fi).

iOS: Settings → General → VPN & Device Management → install the profile, then Settings → General → About → Certificate Trust Settings → enable full trust.

Android: Settings → Security → Install a certificate → CA certificate → select the downloaded file.

Compare

See how amux compares to other AI coding tools:

Use Cases

For Your Stack

By Role

Resources

Security

Local-first. No auth built in — use Tailscale or bind to localhost. Never expose port 8822 to the internet.

About

Open-source Claude Code agent multiplexer — run dozens of parallel AI coding agents unattended via tmux

amux.io

Topics

python tmux automation developer-tools parallel-processing ai-agents claude llm agent-orchestration claude-code

Resources

Readme

License

View license
Activity
Custom properties

Stars

149 stars

Watchers

2 watching

Forks

14 forks
Report repository

Releases

18 tags

Packages

 
 
 

Contributors

Languages