The core problem: Claude Code sessions crash at 3am from context compaction, agents silently block on permission prompts, and there's no good way to see which of your 8 running sessions actually needs attention. I was losing work and wasting money.
amux is a tmux-based multiplexer that gives you a single control plane for all your headless Claude Code sessions — from a web dashboard, your phone, or the CLI.
*What it actually does:*
- Registers Claude Code sessions as named tmux panes, each with its own conversation history and working directory - Live status detection (working / needs input / idle) streamed via SSE — you see at a glance which agents need you - Self-healing watchdog that auto-compacts context, restarts crashed sessions, and replays the last message - Built-in kanban board backed by SQLite with atomic task claiming (CAS), so agents can pick up work items without race conditions - REST API for everything — agents discover peers and delegate work via `curl`. The API reference gets injected into each agent's global memory, so plain-English orchestration works out of the box - Per-session token tracking with daily spend breakdowns, so you know what each agent costs before the bill arrives - Git conflict detection that warns when two agents share a directory + branch, with one-click branch isolation
*What it's not:*
It's not a wrapper around Claude Code's native agent teams feature. It operates at a layer below that — it doesn't modify Claude Code at all. It parses ANSI-stripped tmux output. No hooks, no patches, no monkey-patching. If Claude Code updates tomorrow, amux still works.
*Technical decisions:*
The whole thing is a single ~12,000-line Python file with inline HTML/CSS/JS. No npm, no build step, no Docker. I know the single-file approach is polarizing, but for a tool that runs on your dev machine and you might want to hack on, I've found it dramatically lowers the barrier. It restarts on save.
TLS is auto-provisioned in priority order: Tailscale cert → mkcert → self-signed fallback. The idea is you install it on your dev box, run `amux serve`, and access it securely from your phone over Tailscale while you're away from your desk. I use the mobile PWA daily — kick off a batch of tasks, go walk the dog, check progress from my phone.
The kanban board uses SQLite with compare-and-swap for task claiming. This matters because when you have multiple agents that can pick up work, you need atomicity — two agents hitting `/api/board/PROJ-5/claim` simultaneously should result in exactly one of them getting it.