Getting Started with amux

From zero to running parallel AI agents in under 5 minutes. Updated July 2026.

Quick answer: amux installs in under 2 minutes from a single git clone. Run ./install.sh, register a project, and amux start — that's it. One command gives you a dashboard at localhost:8822 to watch all your agents, steer them, track their plans, and coordinate tasks across sessions.

Prerequisites

python3 (3.8+)
tmux
claude CLI (Claude Code) installed and authenticated — or codex / gemini CLI if you prefer those runtimes

Step 1: Clone and install

git clone https://github.com/mixpeek/amux && cd amux
./install.sh

install.sh copies the amux CLI to /usr/local/bin and starts the server process. No pip packages, no node_modules, no Docker — it's a single Python file with zero external dependencies.

Step 2: Register your first project

amux register myproject --dir ~/Dev/myproject --yolo

--yolo sets permissive mode — the agent can run shell commands and edit files without confirmation prompts. Drop it if you want manual approval for each action.

Step 3: Start the session

amux start myproject

This launches a tmux session running Claude Code (or your configured runtime), watched by amux's self-healing watchdog. If the agent hangs or crashes, it's automatically restarted. Add --detach to return the terminal immediately and let the session run in the background.

Step 4: Open the dashboard

# The server starts automatically on install. Open in your browser:
# https://localhost:8822

The dashboard shows your session card with live status, token usage, the agent's current plan strip, and a send bar. From here you can:

Send steering prompts to any running session
Peek at the agent's live output and scroll the transcript
Create board tasks and assign them to sessions
Watch the self-healing watchdog status
Open the Scheduler tab to set up recurring prompts

Step 5: Send your first task

Click the session card, type a prompt in the send bar, and hit Enter. Or from the terminal:

amux send myproject "add unit tests for the auth module"

The prompt is delivered to the running Claude Code session instantly. Watch the plan strip update as the agent breaks down the task.

Scale up: run multiple sessions in parallel

amux register api-work --dir ~/Dev/myproject --yolo
amux register frontend-work --dir ~/Dev/myproject --yolo
amux register docs-work --dir ~/Dev/myproject --yolo

amux start api-work
amux start frontend-work
amux start docs-work

The dashboard shows all sessions at a glance. Each has its own token budget, plan strip, and self-healing watchdog. See Running 10+ AI Agents in Parallel for multi-session tuning.

How amux compares to the alternatives

Method	Setup time	Parallel agents	Dashboard	Self-healing
amux	Under 2 min	✓ unlimited	✓ web + iOS	✓ watchdog + auto-restart
Bare tmux	5–30 min scripting	✓ manual	✗ terminal only	✗ none
Claude Code alone	Instant	One window at a time	✗ none	✗ none
Devin	Account signup	✓ cloud-managed	✓ SaaS	✓ managed
LangGraph	Days (code a graph)	✓ programmatic	Studio UI	✗ custom code

Frequently Asked Questions

What is amux?

amux is an open-source control plane for running an AI engineering team from a single dashboard or your phone. It launches, monitors, and self-heals dozens of parallel Claude Code, Codex, or Gemini CLI sessions, with built-in kanban, notes, CRM, email, browser automation, and a scheduler. Self-healing, single Python file, zero external dependencies, MIT licensed.

Does amux work with Codex and Gemini CLI too?

Yes. amux is model-agnostic. Each session can run Claude Code, OpenAI Codex CLI, or Gemini CLI — specify the provider when registering. The dashboard, self-healing, scheduler, and board all work the same regardless of runtime. You can mix providers across sessions in the same dashboard.

How many agents can I run at once?

As many as your machine's CPU, RAM, and API rate limits allow. Most developers run 5–15 sessions on a modern laptop. Each session is a tmux pane running an AI CLI; the amux overhead is minimal. See Running 10+ Agents in Parallel and Scaling to 50 agents for hardware and rate-limit recommendations.

Is amux free?

The core amux server is MIT licensed and free forever. The only paid feature is the amux Cloud tunnel relay ($20/mo), which gives your dashboard a stable public HTTPS URL at https://<id>.t.amux.io/. Everything else — dashboard, self-healing, scheduler, board, CRM, email, browser automation — is free and open source. See amux Cloud vs open source.

How do I run agents from my phone?

Install the iOS app (App Store: amux – Agent Multiplexer) or open the dashboard on your phone's browser and install it as a PWA. The mobile interface shows session cards, live status, a peek panel, and a steering bar — all optimized for touch. See Mobile PWA & iOS app.

Get started with amux

Open-source control plane for AI agent teams — self-healing, phone-first, single Python file, zero external dependencies, MIT licensed.

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

★ Star on GitHub Run 10+ agents →