One thing I learned the hard way about tmux-based approaches: tmux sends screen redraws rather than raw output, which breaks scrollback in web-based terminal renderers (xterm.js specifically). If you're streaming tmux pane output to the web dashboard, you might run into this — the terminal looks fine but you can't scroll up through history. tmux control mode (-CC) fixes it by providing raw pane output, but it's a different protocol to parse.
The single-file approach is interesting. How are you handling the web dashboard —inline HTML served from the Python process? Curious how the live status detection works at the tmux level. Are you parsing pane content or watching for output activity on a timer?
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.
