amux -- Agent Multiplexer

Multi-agent coordination for AI coding agents. Agents discover each other, communicate via file-based inboxes, share documents, manage tasks, and build shared knowledge.

Framework-agnostic core with a Pi extension included.

Vision

amux turns isolated AI coding agents into an aligned, communicating team that can deliver outcomes no single agent can reliably achieve alone.

The project optimizes for efficient communication, high alignment, and synergistic collaboration: task-scoped discussion instead of scattered messages, state-derived context instead of stale instructions, and structured work coordination so specialized agents can plan, build, review, and harden software together.

See VISION.md for the full vision, principles, and rationale.

Architecture

core/                          Pi-independent, reusable
  storage.ts                   Shared storage layer (paths, JSON/JSONL I/O)
  registry.ts                  Agent identity (UUID, online/offline)
  messaging.ts                 Crash-safe file-based inboxes
  backlog.ts                   Ordered backlog queue (BacklogItem)
  task-comments.ts             Task-scoped comments and activity
  reservations.ts              File/directory reservations
  journal.ts                   Decision & learning log
  index.ts                     Public API + built-in roles

pi/                            Pi extension (uses core)
  index.ts                     Tools, commands, prompt injection

cli/                           Command-line interface (uses core)
  index.ts                     CLI entry point

Install

Pi Extension

# Stable (npm)
pi install npm:@amutix/amux

# Latest (git)
pi install git:github.com/amutix/amux

Standalone (core module)

git clone https://github.com/amutix/amux.git

Import the core module directly in your project:

import { createAgent, sendMessage, addTask } from "./amux/core/index.ts";

CLI (read-only, phase 1)

amux progress [--session <name>]     # Project progress overview
amux show <ITEM-ID> [--session <name>]  # Item details + comments
amux list [--session <name>]          # Backlog listing
amux task list [--session <name>]     # Backlog listing (explicit namespace)
amux status [--session <name>]        # Agent availability
amux --help                           # Show available commands

Session is auto-detected if only one exists. The CLI uses shared core services and renderers. For full interactive workflows (create, assign, pick, manage), use the Pi extension.

Quick Start (Pi)

# Terminal 1: set up the project
pi
/amux manage          # → Projects > New → create project
/amux project vision set "Build ..."  # first alignment artifact for agents
                      # → Roles > New → define roles (or use built-ins)
                      # → Agents > New → create agents with workspaces
/amux join            # → select project → select your agent

# Terminal 2: another agent joins
cd ~/myapp-agent1 && pi
/amux join            # → select project → select agent → start working

Commands

All commands are subcommands of /amux:

| Command | Purpose | |---------|--------| | /amux | Status and available commands | | /amux join | Join a project as an agent | | /amux leave | Leave project, return to solo mode | | /amux manage | Manage projects, agents, and roles (browse UI) | | /amux progress | Project progress overview | | /amux show <ITEM-ID> | Show backlog item details, comments, parent context, and spec preview | | /amux new <type> | Create project, agent, or role directly | | /amux project | Show/set project vision/context | | /amux context | Legacy alias for project context (CONTEXT.md) | | /amux wow | Show/set team Ways of Working (WOW.md) | | /amux prompt | Preview the amux coordination block appended to your system prompt (debug) | | /amux status set | Set your availability (idle/working/focus/away) | | /amux workspace | Git workspace operations (sync, status) |

Shortcuts

/amux new project [name] [--repo current|<path>] [--vision <text>]
/amux new agent [name] [--role <role>] [--workspace worktree|current|none] [--join]
/amux new role [name]

Missing fields are prompted interactively. New project setup prompts for a project vision/context because it is the first alignment artifact for agents.

Project Vision / Context

/amux project                         # Show current project vision/context
/amux project vision set <t>          # Replace project vision/context
/amux project vision append <t>       # Append to project vision/context
/amux project vision edit             # Open editor to edit CONTEXT.md
/amux project vision clear            # Clear project vision/context
/amux project vision path             # Print CONTEXT.md file path

Legacy aliases remain available:

/amux context [show|edit|set|append|clear|path]

Project vision/context is stored in artifacts/project/CONTEXT.md and auto-injected into agent prompts. Prefer /amux project vision ... or the amux_project tool over direct file edits.

Ways of Working

/amux wow                         # Show current team Ways of Working
/amux wow set <text>              # Replace WOW.md
/amux wow append <text>           # Append to WOW.md
/amux wow edit                    # Open editor to edit WOW.md
/amux wow clear                   # Clear WOW.md
/amux wow path                    # Print WOW.md file path

Ways of Working is stored in artifacts/project/WOW.md and auto-injected into agent prompts after the built-in common principles. Use it for project-specific collaboration norms: planning depth, review policy, definition of done, communication defaults, escalation, and retro habits. Keep it concise because it appears in every agent's prompt. Agents can also use the amux_wow tool.

Prompt preview

/amux prompt                      # Section summary for this agent
/amux prompt roleProfile          # Preview one section
/amux prompt all                  # Explicitly show the full amux-appended block

amux appends a coordination block to the host agent runtime's base system prompt — it never replaces the base prompt. /amux prompt is a debug surface for understanding what each agent actually sees. By default it shows a compact section summary to avoid dumping the whole prompt; inspect a single section by name (for example teamContext) or use /amux prompt all when you explicitly want the full amux-appended block. The host's base system prompt is not shown (amux never sees or owns it). The preview uses the same gathering path that injects the live prompt, so it never drifts from what agents receive.

Task Workflow

Task assignments are state-derived — agents discover their tasks from the current backlog, not from queued inbox messages. This ensures task context is always current and never stale.

# View task details + comment history
/amux show TASK-01
amux_task({ action: "show", id: "TASK-01" })

# Add a task-scoped comment (like PR comments)
amux_task({ action: "comment", id: "TASK-01", content: "Looks good, one suggestion..." })

# Compact project progress overview
/amux progress
amux_task({ action: "summary" })

Lifecycle events (assign, pick, review, done, drop, block) are automatically recorded as activity in task-comments/<ITEM-ID>.jsonl. Use review when implementation is ready for review/integration; use done when work is reviewed, integrated, and verified. Simple workflows can still mark work done directly. Use amux_send only for exceptional non-task communication; delivered messages show intent and age so stale context is visible.

For token-efficient review handoff, include a compact free-form summary when marking work ready for review:

amux_task({
  action: "review",
  id: "TASK-01",
  summary: "Commit abc123 on agent/alice. Diff: extracted auth parser. Tests: npm test. Risk: token refresh edge cases."
})

Reviewer flow: read the linked spec, inspect the diff, inspect test output, then add a task comment or mark the item done. This keeps review scoped to spec + diff + tests instead of reloading broad project context.

When shaping larger work, create the high-level item first (initiative or milestone), add child executable items, review the structure with /amux progress, then assign the leaf work. Assign task/bug/chore/spec items rather than container items unless you intentionally want broad ownership.

Documentation types:

| Type | Use for | Tool | |------|---------|------| | Task description | Brief inline context and acceptance criteria | amux_task add | | Linked spec | Detailed plans, checklists, design notes | amux_task plan/edit-plan | | Journal | Decisions, learnings, progress shared across agents | amux_journal add |

Recommended workflow: Create a high-level initiative with child tasks, assign all executable leaves to the intended agent(s) upfront, and let dependsOn enforce ordering. The assignee picks one task at a time after completing the current one. Auto-pick (amux_task pick without an ID) prefers assigned-to-self items with met dependencies before open todo items.

Backlog Model

Backlog items (BacklogItem) support optional structure fields:

| Field | Purpose | |-------|---------| | itemType | task (default), initiative, milestone, bug, chore, spec | | dependsOn | Array of task IDs that must be done before this item can be picked | | parentId | Parent item ID for hierarchy grouping | | order | Sort order within siblings |

Existing items without these fields behave as regular tasks. New item IDs use type-specific prefixes: TASK-*, INIT-*, MS-*, BUG-*, CHORE-*, and SPEC-*. Existing TASK-* IDs remain valid.

Availability

/amux status set idle        # Ready for new work
/amux status set working     # Actively working (auto-set on pick)
/amux status set focus       # Do not interrupt
/amux status set away        # Unavailable

Availability is auto-updated by task lifecycle: pick → working, done/drop → idle (preserves explicit focus/away). Idle agents receive a single generic attention signal when new work is assigned; working/focus/away agents are not interrupted.

Manage

/amux manage
  → Projects     new, rename, delete, set main repo
  → Agents       new (with role + optional workspace), rename, delete
  → Roles        new, delete

Tools (10)

| Tool | Actions | Purpose | |------|---------|---------| | amux_role | add, list, remove, templates, apply-template, show, path | Manage roles and apply team templates | | amux_list | -- | List online/offline agents | | amux_send | -- | Send message to an agent (exceptional, non-task communication) | | amux_broadcast | -- | Broadcast to all agents | | amux_artifacts | -- | List shared documents | | amux_project | show, set, append, clear, path | Manage project vision/context | | amux_wow | show, set, append, clear, path | Manage project/team Ways of Working | | amux_reserve | claim, release, list | File/directory reservations | | amux_task | add, list, show, comment, assign, pick, review, done, drop, block, summary | Task backlog with comments, dependencies, batch assign | | amux_journal | add, list | Record decisions and learnings |

Built-in Roles

Five role templates ship with amux, ready to use during agent creation:

| Role | Description | |------|-------------| | developer | Write clean, well-structured code | | architect | System design, trade-offs, technical decisions | | reviewer | Code review, quality, constructive feedback | | devops | Infrastructure, CI/CD, deployment | | planner | Task breakdown, requirements, coordination |

Built-in roles are copied to the project on first use and can be customized.

Role Profiles & Team Templates

For lead-agent orchestration, amux ships richer role profiles (markdown) and team templates for quick setup.

Bundled role profiles (roles/*.md):

| Profile | Focus | |---------|-------| | lead-architect | Decompose goals, delegate, coordinate, guard quality | | developer | Implement assigned tasks from specs, write tests | | reviewer | Verify implementations against specs and acceptance criteria |

Team templates (team-templates/*.json):

| Template | Roles | |----------|-------| | core-team | lead-architect + developer + reviewer |

amux_role({ action: "templates" })                       # list bundled profiles + teams
amux_role({ action: "apply-template", template: "core-team" })  # copy profiles + register roles
amux_role({ action: "show", name: "lead-architect" })    # resolved role text
amux_role({ action: "path", name: "lead-architect" })    # project-local profile file path

Applying a team template copies the role markdown into artifacts/project/roles/ and registers role definitions. It does not create agents — create those separately via /amux manage or /amux new agent. The copied markdown is the source of truth (profilePath); edit it to customize a role. Existing customized profiles are preserved unless force is used. Legacy roles with inline instructions continue to work unchanged.

Lead Orchestration Workflow

amux is built for a lead agent (e.g. the lead-architect role) to turn high-level user goals into coordinated, reviewed delivery through a team of specialists. The recommended lead loop:

1. Clarify the goal — outcomes, constraints, non-goals.
2. Confirm/update project vision — amux_project (durable, prompt-injected context).
3. Create structure — an initiative/milestone/spec for the work.
4. Decompose — break into executable leaf tasks with files and dependsOn.
5. Delegate — assign executable leaves to specialists (not container items); assign ready leaves up front and let dependsOn enforce order.
6. Monitor — amux_task summary / /amux progress, reservations, review status.
7. Require review — substantive work goes to review before done.
8. Integrate — verify and merge the final changes.
9. Report — give the user a clear outcome: what shipped, files/commits, tests, decisions, risks, next steps.

This workflow is guidance, not magic automation — the lead agent orchestrates through the existing primitives (amux_task, amux_project, reservations, journal). There is no auto-decomposition action; decomposition is the lead's judgment and stays reviewable.

Prompt composition

amux appends a composed coordination block to the host agent runtime's base system prompt (it never replaces it). The block is assembled in a deliberate, documented order (see core/prompt-assembly.ts):

1. Common amux operating principles (collaboration contract)
2. Project vision/context
3. Role profile (role-specific only)
4. Agent identity + workspace
5. Current work state (active/assigned/review items, spec preview, recent comments)
6. Team/project snapshot/reservation context
7. Interface/tool guidance and shared artifact paths

Role profiles supply only the role-specific section; common principles, vision, work state, and interface guidance are separate, deliberately-ordered sections.

Team Learning & Retrospectives

amux teams learn from mistakes, successes, and user corrections through curated learnings — selective, durable lessons that evolve how the team works.

Artifact boundaries

| Artifact | Purpose | Changes how | |----------|---------|-------------| | CONTEXT.md | Project vision and strategy | Via /amux context or amux_project | | WOW.md | Team collaboration norms | Via /amux wow or amux_wow | | role profiles | Per-role behavior | Via editing roles/<name>.md | | journal.jsonl | Curated lessons, decisions, proposals | Via amux_journal add |

Retrospectives

After completing a major initiative or milestone, the lead runs a lightweight retro (no new command — just 4 questions through existing primitives):

1. What worked?
2. What failed or caused rework?
3. What user correction should we remember?
4. What should change in WoW, role profiles, or project context?

Outputs are recorded as amux_journal learning entries. Norm-changing proposals use the context: "wow-proposal" convention — the journal entry is the proposal; WoW only changes by deliberate lead/user edit via /amux wow. Nothing auto-mutates.

Workspaces

Agents can work in isolated git worktrees:

# Architect sets up (from /amux manage)
Agents > New → name, role, workspace: "New worktree"
  → creates ~/myapp-alice on branch agent/alice
  (names are sanitized: "My Agent!" → agent/my-agent)

# Agent starts in their worktree
cd ~/myapp-alice && pi
/amux join

# Sync from main (fetches origin, rebases on origin/<mainBranch>)
/amux workspace > sync

# Check status (compares against origin/<mainBranch>)
/amux workspace > status

Sync runs git fetch origin followed by git rebase origin/<mainBranch>, where <mainBranch> is the current branch of the main repo (defaults to main). This avoids rebasing against a stale local branch. Status compares commit counts against the same remote ref and handles missing refs gracefully.

Key Features

• Framework-agnostic core -- works with any agent framework, not just Pi
• Zero overhead -- invisible until you opt in
• UUID identity -- 128-bit UUIDs, unique names per session (case-insensitive), agents persist across restarts
• Heartbeat presence -- crashed agents auto-expire after 90s, stale reservations cleared automatically
• Agent availability -- idle/working/focus/away status, auto-updated by task lifecycle, generic attention signals for idle agents
• Crash-safe messaging -- messages survive crashes, delivered on reconnect
• File reservations -- claim files before editing; conflicts show age, linked task context, and owner work state
• Task backlog -- state-derived workflow with task-scoped comments, dependencies, batch assign, assignee ownership. Assignments are visible via task state, not inbox messages.
• Shared journal -- decisions and learnings in every agent's context
• Git workspaces -- isolated worktrees per agent
• Built-in roles -- ready to use, customizable per project
• Zero dependencies -- just Node.js

Session Files

Default root: ~/.amux/sessions/. Override with environment variables:

| Variable | Effect | |----------|--------| | AMUX_SESSIONS_DIR | Use this path as the sessions directory (highest priority) | | AMUX_HOME | Use $AMUX_HOME/sessions as the sessions directory |

Both core modules and the Pi adapter resolve the same root.

~/.amux/sessions/<project>/
├── agents.json             Agent registry (UUID-keyed)
├── roles.json              Role definitions
├── config.json             Project config (main repo path)
├── backlog.json            Task backlog
├── task-comments/          Per-task comment/activity history (JSONL)
├── reservations.json       File reservations
├── journal.jsonl           Decisions & learnings
├── messages.log            Message history
├── inbox/<agent-uuid>/     Per-agent message inbox
└── artifacts/
    ├── project/            Shared across all agents
    │   └── CONTEXT.md      Auto-injected into agent prompts
    └── agents/<uuid>/      Private per-agent space

Development

Requires Node >= 22 (uses --experimental-strip-types).

npm test    # Parse-check all .ts files + run E2E flow tests

Benchmarks

See benchmarks/solo-vs-amux/ for the solo-vs-amux token efficiency benchmark harness.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT -- see LICENSE.