{"_id":"@amutix/amux","_rev":"2-7166c796f7a0d98ab871f04ee6be1f98","name":"@amutix/amux","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@amutix/amux","version":"1.0.0","keywords":["pi-package","multi-agent","agent-coordination","ai-agents"],"author":{"name":"rezabaram"},"license":"MIT","_id":"@amutix/amux@1.0.0","maintainers":[{"name":"rezabaram","email":"reza.baram@gmail.com"}],"homepage":"https://github.com/amutix/amux","bugs":{"url":"https://github.com/amutix/amux/issues"},"pi":{"extensions":["./pi/index.ts"]},"bin":{"amux":"cli/index.ts"},"dist":{"shasum":"449f5fa3ed7eda021b5588a1729bcf3cedc4837b","tarball":"https://registry.npmjs.org/@amutix/amux/-/amux-1.0.0.tgz","fileCount":13,"integrity":"sha512-JXe7fCksCmsm5xx7r/K+T+2KYI/2VYf2Gxliuqvv6S6YPs79YUrwNxZ8MkXZ5xmkdefECxFndupGCbP5aGErHA==","signatures":[{"sig":"MEQCIAbuUO5mo7LjI60HyyGrznvkjGlicr9AOwnYlXj2Pm2OAiAUgz4S47RAGWWMcCL4e9McEWkdxQjeS9PD2taPKnZq9g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":118830},"type":"module","engines":{"node":">=22"},"gitHead":"21d9e0ddebac3ec7afd4da359da734cd1294fc66","scripts":{"test":"node test/parse.mjs && node --test test/flows.ts"},"_npmUser":{"name":"rezabaram","email":"reza.baram@gmail.com"},"repository":{"url":"git+https://github.com/amutix/amux.git","type":"git"},"_npmVersion":"11.4.2","description":"Agent Multiplexer -- multi-agent coordination for AI coding agents","directories":{},"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/amux_1.0.0_1781978122085_0.8704130129892516","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@amutix/amux","version":"1.2.0","description":"Agent Multiplexer -- multi-agent coordination for AI coding agents","type":"module","keywords":["pi-package","multi-agent","agent-coordination","ai-agents"],"repository":{"type":"git","url":"git+https://github.com/amutix/amux.git"},"homepage":"https://github.com/amutix/amux","bugs":{"url":"https://github.com/amutix/amux/issues"},"author":{"name":"rezabaram"},"license":"MIT","engines":{"node":">=22"},"bin":{"amux":"cli/index.ts"},"scripts":{"test":"node --experimental-strip-types test/parse.mjs && node --experimental-strip-types --test test/flows.ts"},"pi":{"extensions":["./pi/index.ts"]},"publishConfig":{"access":"public"},"_id":"@amutix/amux@1.2.0","gitHead":"678ebfbd217e08b2e2ee63709f4cde208a43aa72","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-ka1RhYTQ12ykQbew7Ynr0Vqql4g76L0MElZHCva6lSpL280eGIdMUnvIzC3zT/weorGRwbkEQeKphEPDvMjg+w==","shasum":"d57697a5882fad58eb463785cb8dcf94ac1c85ce","tarball":"https://registry.npmjs.org/@amutix/amux/-/amux-1.2.0.tgz","fileCount":38,"unpackedSize":295255,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIANHqSWvtnwWce2cr6ysv9xtRSHAweRgWZ0J89146oIRAiBHkl+bzHv2Rkq2xxx6FiQ4rKaMu0ZqG8qT/kWInu6uaA=="}]},"_npmUser":{"name":"rezabaram","email":"reza.baram@gmail.com"},"directories":{},"maintainers":[{"name":"rezabaram","email":"reza.baram@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/amux_1.2.0_1782146722328_0.9821847684547296"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-20T17:55:22.001Z","modified":"2026-06-22T16:45:22.614Z","1.0.0":"2026-06-20T17:55:22.275Z","1.2.0":"2026-06-22T16:45:22.498Z"},"bugs":{"url":"https://github.com/amutix/amux/issues"},"author":{"name":"rezabaram"},"license":"MIT","homepage":"https://github.com/amutix/amux","keywords":["pi-package","multi-agent","agent-coordination","ai-agents"],"repository":{"type":"git","url":"git+https://github.com/amutix/amux.git"},"description":"Agent Multiplexer -- multi-agent coordination for AI coding agents","maintainers":[{"name":"rezabaram","email":"reza.baram@gmail.com"}],"readme":"# amux -- Agent Multiplexer\n\nMulti-agent coordination for AI coding agents. Agents discover each other, communicate via file-based inboxes, share documents, manage tasks, and build shared knowledge.\n\nFramework-agnostic core with a [Pi](https://github.com/earendil-works/pi) extension included.\n\n## Vision\n\namux turns isolated AI coding agents into an aligned, communicating team that can deliver outcomes no single agent can reliably achieve alone.\n\nThe 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.\n\nSee [VISION.md](./VISION.md) for the full vision, principles, and rationale.\n\n## Architecture\n\n```\ncore/                          Pi-independent, reusable\n  storage.ts                   Shared storage layer (paths, JSON/JSONL I/O)\n  registry.ts                  Agent identity (UUID, online/offline)\n  messaging.ts                 Crash-safe file-based inboxes\n  backlog.ts                   Ordered backlog queue (BacklogItem)\n  task-comments.ts             Task-scoped comments and activity\n  reservations.ts              File/directory reservations\n  journal.ts                   Decision & learning log\n  index.ts                     Public API + built-in roles\n\npi/                            Pi extension (uses core)\n  index.ts                     Tools, commands, prompt injection\n\ncli/                           Command-line interface (uses core)\n  index.ts                     CLI entry point\n```\n\n## Install\n\n### Pi Extension\n\n```bash\n# Stable (npm)\npi install npm:@amutix/amux\n\n# Latest (git)\npi install git:github.com/amutix/amux\n```\n\n### Standalone (core module)\n\n```bash\ngit clone https://github.com/amutix/amux.git\n```\n\nImport the core module directly in your project:\n\n```typescript\nimport { createAgent, sendMessage, addTask } from \"./amux/core/index.ts\";\n```\n\n### CLI (read-only, phase 1)\n\n```bash\namux progress [--session <name>]     # Project progress overview\namux show <ITEM-ID> [--session <name>]  # Item details + comments\namux list [--session <name>]          # Backlog listing\namux task list [--session <name>]     # Backlog listing (explicit namespace)\namux status [--session <name>]        # Agent availability\namux --help                           # Show available commands\n```\n\nSession 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.\n\n## Quick Start (Pi)\n\n```bash\n# Terminal 1: set up the project\npi\n/amux manage          # → Projects > New → create project\n/amux project vision set \"Build ...\"  # first alignment artifact for agents\n                      # → Roles > New → define roles (or use built-ins)\n                      # → Agents > New → create agents with workspaces\n/amux join            # → select project → select your agent\n\n# Terminal 2: another agent joins\ncd ~/myapp-agent1 && pi\n/amux join            # → select project → select agent → start working\n```\n\n## Commands\n\nAll commands are subcommands of `/amux`:\n\n| Command | Purpose |\n|---------|--------|\n| `/amux` | Status and available commands |\n| `/amux join` | Join a project as an agent |\n| `/amux leave` | Leave project, return to solo mode |\n| `/amux manage` | Manage projects, agents, and roles (browse UI) |\n| `/amux progress` | Project progress overview |\n| `/amux show <ITEM-ID>` | Show backlog item details, comments, parent context, and spec preview |\n| `/amux new <type>` | Create project, agent, or role directly |\n| `/amux project` | Show/set project vision/context |\n| `/amux context` | Legacy alias for project context (CONTEXT.md) |\n| `/amux wow` | Show/set team Ways of Working (WOW.md) |\n| `/amux prompt` | Preview the amux coordination block appended to your system prompt (debug) |\n| `/amux status set` | Set your availability (idle/working/focus/away) |\n| `/amux workspace` | Git workspace operations (sync, status) |\n\n### Shortcuts\n\n```bash\n/amux new project [name] [--repo current|<path>] [--vision <text>]\n/amux new agent [name] [--role <role>] [--workspace worktree|current|none] [--join]\n/amux new role [name]\n```\n\nMissing fields are prompted interactively. New project setup prompts for a project vision/context because it is the first alignment artifact for agents.\n\n### Project Vision / Context\n\n```bash\n/amux project                         # Show current project vision/context\n/amux project vision set <t>          # Replace project vision/context\n/amux project vision append <t>       # Append to project vision/context\n/amux project vision edit             # Open editor to edit CONTEXT.md\n/amux project vision clear            # Clear project vision/context\n/amux project vision path             # Print CONTEXT.md file path\n```\n\nLegacy aliases remain available:\n\n```bash\n/amux context [show|edit|set|append|clear|path]\n```\n\nProject 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.\n\n### Ways of Working\n\n```bash\n/amux wow                         # Show current team Ways of Working\n/amux wow set <text>              # Replace WOW.md\n/amux wow append <text>           # Append to WOW.md\n/amux wow edit                    # Open editor to edit WOW.md\n/amux wow clear                   # Clear WOW.md\n/amux wow path                    # Print WOW.md file path\n```\n\nWays 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.\n\n### Prompt preview\n\n```bash\n/amux prompt                      # Section summary for this agent\n/amux prompt roleProfile          # Preview one section\n/amux prompt all                  # Explicitly show the full amux-appended block\n```\n\namux **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.\n\n### Task Workflow\n\nTask 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.\n\n```bash\n# View task details + comment history\n/amux show TASK-01\namux_task({ action: \"show\", id: \"TASK-01\" })\n\n# Add a task-scoped comment (like PR comments)\namux_task({ action: \"comment\", id: \"TASK-01\", content: \"Looks good, one suggestion...\" })\n\n# Compact project progress overview\n/amux progress\namux_task({ action: \"summary\" })\n```\n\nLifecycle 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.\n\nFor token-efficient review handoff, include a compact free-form summary when marking work ready for review:\n\n```bash\namux_task({\n  action: \"review\",\n  id: \"TASK-01\",\n  summary: \"Commit abc123 on agent/alice. Diff: extracted auth parser. Tests: npm test. Risk: token refresh edge cases.\"\n})\n```\n\nReviewer 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.\n\nWhen 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.\n\n**Documentation types:**\n\n| Type | Use for | Tool |\n|------|---------|------|\n| Task description | Brief inline context and acceptance criteria | `amux_task add` |\n| Linked spec | Detailed plans, checklists, design notes | `amux_task plan/edit-plan` |\n| Journal | Decisions, learnings, progress shared across agents | `amux_journal add` |\n\n**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.\n\n### Backlog Model\n\nBacklog items (`BacklogItem`) support optional structure fields:\n\n| Field | Purpose |\n|-------|---------|\n| `itemType` | `task` (default), `initiative`, `milestone`, `bug`, `chore`, `spec` |\n| `dependsOn` | Array of task IDs that must be done before this item can be picked |\n| `parentId` | Parent item ID for hierarchy grouping |\n| `order` | Sort order within siblings |\n\nExisting 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.\n\n### Availability\n\n```bash\n/amux status set idle        # Ready for new work\n/amux status set working     # Actively working (auto-set on pick)\n/amux status set focus       # Do not interrupt\n/amux status set away        # Unavailable\n```\n\nAvailability 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.\n\n### Manage\n\n```\n/amux manage\n  → Projects     new, rename, delete, set main repo\n  → Agents       new (with role + optional workspace), rename, delete\n  → Roles        new, delete\n```\n\n## Tools (10)\n\n| Tool | Actions | Purpose |\n|------|---------|---------|\n| `amux_role` | add, list, remove, templates, apply-template, show, path | Manage roles and apply team templates |\n| `amux_list` | -- | List online/offline agents |\n| `amux_send` | -- | Send message to an agent (exceptional, non-task communication) |\n| `amux_broadcast` | -- | Broadcast to all agents |\n| `amux_artifacts` | -- | List shared documents |\n| `amux_project` | show, set, append, clear, path | Manage project vision/context |\n| `amux_wow` | show, set, append, clear, path | Manage project/team Ways of Working |\n| `amux_reserve` | claim, release, list | File/directory reservations |\n| `amux_task` | add, list, show, comment, assign, pick, review, done, drop, block, summary | Task backlog with comments, dependencies, batch assign |\n| `amux_journal` | add, list | Record decisions and learnings |\n\n## Built-in Roles\n\nFive role templates ship with amux, ready to use during agent creation:\n\n| Role | Description |\n|------|-------------|\n| `developer` | Write clean, well-structured code |\n| `architect` | System design, trade-offs, technical decisions |\n| `reviewer` | Code review, quality, constructive feedback |\n| `devops` | Infrastructure, CI/CD, deployment |\n| `planner` | Task breakdown, requirements, coordination |\n\nBuilt-in roles are copied to the project on first use and can be customized.\n\n## Role Profiles & Team Templates\n\nFor lead-agent orchestration, amux ships richer **role profiles** (markdown) and **team templates** for quick setup.\n\n**Bundled role profiles** (`roles/*.md`):\n\n| Profile | Focus |\n|---------|-------|\n| `lead-architect` | Decompose goals, delegate, coordinate, guard quality |\n| `developer` | Implement assigned tasks from specs, write tests |\n| `reviewer` | Verify implementations against specs and acceptance criteria |\n\n**Team templates** (`team-templates/*.json`):\n\n| Template | Roles |\n|----------|-------|\n| `core-team` | lead-architect + developer + reviewer |\n\n```bash\namux_role({ action: \"templates\" })                       # list bundled profiles + teams\namux_role({ action: \"apply-template\", template: \"core-team\" })  # copy profiles + register roles\namux_role({ action: \"show\", name: \"lead-architect\" })    # resolved role text\namux_role({ action: \"path\", name: \"lead-architect\" })    # project-local profile file path\n```\n\nApplying 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.\n\n## Lead Orchestration Workflow\n\namux 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:\n\n1. **Clarify the goal** — outcomes, constraints, non-goals.\n2. **Confirm/update project vision** — `amux_project` (durable, prompt-injected context).\n3. **Create structure** — an initiative/milestone/spec for the work.\n4. **Decompose** — break into executable leaf tasks with `files` and `dependsOn`.\n5. **Delegate** — assign executable leaves to specialists (not container items); assign ready leaves up front and let `dependsOn` enforce order.\n6. **Monitor** — `amux_task summary` / `/amux progress`, reservations, review status.\n7. **Require review** — substantive work goes to `review` before `done`.\n8. **Integrate** — verify and merge the final changes.\n9. **Report** — give the user a clear outcome: what shipped, files/commits, tests, decisions, risks, next steps.\n\nThis 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.\n\n### Prompt composition\n\namux **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`):\n\n1. Common amux operating principles (collaboration contract)\n2. Project vision/context\n3. Role profile (role-specific only)\n4. Agent identity + workspace\n5. Current work state (active/assigned/review items, spec preview, recent comments)\n6. Team/project snapshot/reservation context\n7. Interface/tool guidance and shared artifact paths\n\nRole profiles supply only the role-specific section; common principles, vision, work state, and interface guidance are separate, deliberately-ordered sections.\n\n## Team Learning & Retrospectives\n\namux teams learn from mistakes, successes, and user corrections through **curated learnings** — selective, durable lessons that evolve how the team works.\n\n### Artifact boundaries\n\n| Artifact | Purpose | Changes how |\n|----------|---------|-------------|\n| `CONTEXT.md` | Project vision and strategy | Via `/amux context` or `amux_project` |\n| `WOW.md` | Team collaboration norms | Via `/amux wow` or `amux_wow` |\n| role profiles | Per-role behavior | Via editing `roles/<name>.md` |\n| `journal.jsonl` | Curated lessons, decisions, proposals | Via `amux_journal add` |\n\n### Retrospectives\n\nAfter completing a major initiative or milestone, the lead runs a **lightweight retro** (no new command — just 4 questions through existing primitives):\n\n1. What worked?\n2. What failed or caused rework?\n3. What user correction should we remember?\n4. What should change in WoW, role profiles, or project context?\n\nOutputs 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.\n\n## Workspaces\n\nAgents can work in isolated git worktrees:\n\n```bash\n# Architect sets up (from /amux manage)\nAgents > New → name, role, workspace: \"New worktree\"\n  → creates ~/myapp-alice on branch agent/alice\n  (names are sanitized: \"My Agent!\" → agent/my-agent)\n\n# Agent starts in their worktree\ncd ~/myapp-alice && pi\n/amux join\n\n# Sync from main (fetches origin, rebases on origin/<mainBranch>)\n/amux workspace > sync\n\n# Check status (compares against origin/<mainBranch>)\n/amux workspace > status\n```\n\nSync 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.\n\n## Key Features\n\n- **Framework-agnostic core** -- works with any agent framework, not just Pi\n- **Zero overhead** -- invisible until you opt in\n- **UUID identity** -- 128-bit UUIDs, unique names per session (case-insensitive), agents persist across restarts\n- **Heartbeat presence** -- crashed agents auto-expire after 90s, stale reservations cleared automatically\n- **Agent availability** -- idle/working/focus/away status, auto-updated by task lifecycle, generic attention signals for idle agents\n- **Crash-safe messaging** -- messages survive crashes, delivered on reconnect\n- **File reservations** -- claim files before editing; conflicts show age, linked task context, and owner work state\n- **Task backlog** -- state-derived workflow with task-scoped comments, dependencies, batch assign, assignee ownership. Assignments are visible via task state, not inbox messages.\n- **Shared journal** -- decisions and learnings in every agent's context\n- **Git workspaces** -- isolated worktrees per agent\n- **Built-in roles** -- ready to use, customizable per project\n- **Zero dependencies** -- just Node.js\n\n## Session Files\n\nDefault root: `~/.amux/sessions/`. Override with environment variables:\n\n| Variable | Effect |\n|----------|--------|\n| `AMUX_SESSIONS_DIR` | Use this path as the sessions directory (highest priority) |\n| `AMUX_HOME` | Use `$AMUX_HOME/sessions` as the sessions directory |\n\nBoth core modules and the Pi adapter resolve the same root.\n\n```\n~/.amux/sessions/<project>/\n├── agents.json             Agent registry (UUID-keyed)\n├── roles.json              Role definitions\n├── config.json             Project config (main repo path)\n├── backlog.json            Task backlog\n├── task-comments/          Per-task comment/activity history (JSONL)\n├── reservations.json       File reservations\n├── journal.jsonl           Decisions & learnings\n├── messages.log            Message history\n├── inbox/<agent-uuid>/     Per-agent message inbox\n└── artifacts/\n    ├── project/            Shared across all agents\n    │   └── CONTEXT.md      Auto-injected into agent prompts\n    └── agents/<uuid>/      Private per-agent space\n```\n\n## Development\n\nRequires Node >= 22 (uses `--experimental-strip-types`).\n\n```bash\nnpm test    # Parse-check all .ts files + run E2E flow tests\n```\n\n### Benchmarks\n\nSee [`benchmarks/solo-vs-amux/`](benchmarks/solo-vs-amux/) for the solo-vs-amux token efficiency benchmark harness.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT -- see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}