Agent FrameworkSep 17, 20266 min read

amux Explained: Running Parallel AI Coding Agents

amux: Explore SQLite task claiming, watchdog recovery and coding-agent workflows. Assess the control plane before scheduling parallel agent work.

Docs analysis

Who this is for: Developers evaluating amux.

The answer in 3 lines

  • Explore SQLite task claiming, watchdog recovery and coding-agent workflows.
  • Assess the control plane before scheduling parallel agent work.
  • Evidence: linked documentation; no independent test results are claimed.

Evidence: Analysis of the linked documentation and source-reported behavior; examples and decision tables are explanatory, not executed tests.

AI-assisted documentation analysis · 5 source links

Based on linked documentation and web research. Source-reported benchmarks are attributed to their publishers; this report does not establish independent testing. How reports are produced.

Executive Summary

When scaling AI coding assistants from single interactive sessions to parallel agent fleets, coordinating execution state becomes a critical bottleneck. Without centralized control, independent agents can overlap by refactoring identical functions or editing shared files simultaneously Dan Kornas on X. amux addresses this operational challenge as a single-binary, local-first Rust control plane that orchestrates parallel workers (such as Claude Code, OpenAI Codex CLI, and Gemini CLI) using atomic task claiming, structured messaging, and self-healing watchdog loops.

The primary tradeoff of amux's local-first architecture is its dependency on host operating system automation and process isolation (such as tmux and macOS TCC permissions), which requires explicit system grants and local process management. However, for engineering teams operating parallel agent workloads, amux offers a local control plane that centralizes task and worker state; host automation and agent CLIs remain operating dependencies amux README.

Core Architecture: Single-Binary Rust Server & SQLite Ledger

According to the amux README, amux consolidates its entire control plane into a single Rust binary containing four primary crates:

  1. crates/amux-server: The core HTTP/HTTPS server built on Axum (defaulting to HTTPS port 8824), wrapping a single-writer SQLite store with an append-only event journal, Server-Sent Events (SSE) delta synchronization, and background orchestration runtimes.
  2. crates/amux-dashboard: A single-page web application embedded directly into the server binary during compilation.
  3. crates/amux-cli: The amux-rs command-line utility for managing tasks, workers, schedules, and health status.
  4. crates/amux-core: Shared domain types covering identifiers, scopes, memory layers, and protocol definitions.

State persistence relies entirely on SQLite, avoiding dependencies on external datastores like Redis Best Claude Code Session Managers 2026. To eliminate worker collisions on the shared kanban board, task claiming is implemented using compare-and-swap (CAS) database operations. This means that when dozens of parallel agents attempt to pick up todo items, atomic state transitions are intended to give one worker ownership of a particular claim; this is not proof that separately owned tasks cannot edit the same files amux vs Cline.

Additionally, amux decouples completion from validation by separating task statuses into done (code implemented and merged) and verified (peer-checked or passing CI verification) amux README.

Primitives, Inter-Worker Messaging, and Scope Hierarchy

The amux control plane models multi-agent collaboration through eight fundamental primitives: board, workers, schedulers, filesystem, groups, memories, environment, and messages amux README.

  • Provenance-Stamped Messaging: Inter-worker and human-to-worker communications are logged as structured ledger entries. The server stamps the genuine sender origin on every message, providing origin metadata to inspect during turn boundaries; the application’s trust boundary still needs validation amux README.
  • Hierarchical Scope Resolution: Configuration and context (including system prompts, environment variables, and board gates) resolve dynamically across four layers: card → worker → group → global amux README. For a team operating specialized worker lanes (such as frontend vs backend refactoring groups), this hierarchy describes how configuration resolves. It should not be treated as a demonstrated credential-isolation boundary.

Self-Healing Recovery and Watchdog Controls

Long-running unattended agent operations frequently suffer from context window exhaustion, CLI process crashes, or hung prompts. amux addresses these failure modes through an automated watchdog background task amux vs Cline:

  1. Context Compaction: When token limits are reached, the watchdog triggers context compaction and resumes execution.
  2. Crash Restart & Replay: If an underlying agent process exits unexpectedly, the server restarts the session and replays the last unacknowledged message to restore context.
  3. Stalled Agent Detection: The system identifies sessions that cease outputting tokens and marks them with diagnostic badges to distinguish blocked prompts from fatal crashes Best Claude Code Session Managers 2026.

Computed Markdown Workflows: .mdai Files

To support dynamic document synthesis and multi-stage research pipelines, amux introduces computed markdown files designated by the .mdai extension amux README. A .mdai file functions as a node in a Directed Acyclic Graph (DAG) produced by AI model execution.

When a .mdai node is opened or executed via POST /api/files/mdai/run, amux resolves source dependencies upstream-first, depth-first. The execution runtime includes built-in cycle detection (naming explicit loops if invalid dependencies exist) and input-hash caching amux README. This means that if upstream source contents, prompts, and model definitions remain unchanged, the documented cache can reuse the prior result. Cache validity and retrieval latency should be assessed in the actual environment.

Operational Considerations & macOS System Integration

amux can be deployed on macOS via launchd or on Linux distributions (Ubuntu 22.04+, Debian 11+, Fedora 36+) via systemd user services (amux-server.service, amux-builder.service, amux-builder.timer) amux README.

For developers managing desktop automation, code signing stability (AMUX_CODESIGN_IDENTITY) is required to prevent macOS TCC prompt resets when amux-builder automatically updates server binaries in place amux README.

Selection Guidance & Tradeoffs

  • Choose amux if: You need to run 5 to 50 parallel, unattended AI coding agents overnight with atomic task distribution, self-healing recovery, mobile/web status monitoring, and local-first SQLite persistence amux vs Cline.
  • Choose simpler alternatives (e.g., Claude Squad or DIY tmux) if: You only require 2 or 3 interactive terminal sessions without task board locking, mobile PWA access, or automated crash recovery Best Claude Code Session Managers 2026.
  • Choose IDE extensions (e.g., Cline / Roo Code) if: Your workflow demands step-by-step human tool approval inside VS Code for interactive single-session feature engineering amux vs Cline.

A task-claiming trial is not a merge-conflict trial

Suppose two workers operate on an authentication change and a UI change in the same repository. Atomic board ownership helps prevent both workers claiming one card. It does not establish that separately owned cards cannot touch the same files. Board and worker primitives

TrialEvidence to retainRemaining coordination question
Two workers claim one cardClaim outcome and board historyDoes the intended ownership transition occur?
Different cards edit shared codeChanges and integration checksWho coordinates the overlap and reviews the merged result?
A worker restarts during an actionEvent history and resulting filesCan recovery distinguish completed work from a repeated attempt?

Assign clear file or subsystem boundaries for the pilot and inspect the final integration result, not just each worker's completion message. Keep done and verified meaningful by requiring the evidence appropriate to the task. On macOS, verify the required automation permissions before diagnosing an idle worker as an agent failure.

This test plan distinguishes control-plane ownership, host automation and code correctness. Configuration scopes and provenance-stamped messages improve coordination, but should not be treated as independent proof of credential isolation or spoofing resistance. No fleet trial or host-permission measurement was performed here.

Evidence and scope

Primary repository documentation was refreshed on 14 October 2026. The worked scenario is a planning exercise derived from documented behavior, not a product test. Reported measurements remain attributed to their source and workload.

Keep exploring

Agent persistence & workflows: questions, tradeoffs, and guides →

Browse all reports · Suggest a correction