cmux-agent-teams

cmux-agent-teams

🇺🇸 English | 🇰🇷 한국어

A cmux-based multi-agent parallel execution plugin — Run multiple Claude Code instances simultaneously across cmux terminal panes, with file-based IPC and signal synchronization for real-time collaboration between agents.

Backend-to-backend, frontend-to-frontend, full-stack pipelines, legacy project migrations — any combination works.

---

Fanout — Parallel Execution Demo

Pipeline — Sequential Pipeline Demo

---

---

Table of Contents

• Why Use This?
• Requirements
• Installation
• Usage
• Quick Start
• Architecture
• Use Cases
• Execution Patterns
• IPC Protocol
• Script Reference
• Message Format Reference
• Signal Naming Convention
• Peer-to-Peer Communication
• Sub-agents (teammateMode)
• External Skill Integration
• Limitations & Troubleshooting
• License

---

Why Use This?

The Problem: Single-Session Bottleneck in Claude Code

Claude Code is powerful, but each session can only handle one task at a time. For complex projects, this becomes a serious bottleneck.

Example: A typical API development workflow

Sequential execution (traditional):
  Entity design    [====]                              30 min
  Service impl           [========]                   60 min
  Controller impl                  [======]           45 min
  Frontend integration                    [========]  60 min
  Test writing                                  [====] 30 min
  ─────────────────────────────────────────────────────
  Total: 225 min (3h 45m)

The Solution: Multi-Agent Parallel Execution

With cmux-agent-teams, independent tasks run in parallel, and tasks with dependencies are connected via a signal-based pipeline.

Parallel execution (cmux-agent-teams):
  Entity design    [====]
  Service impl           [========]
  Controller impl                  [======]
  Frontend integration                    [========]
  Test writing           [====][====][====][====]  ← P2P start as each API completes
  ─────────────────────────────────────────────
  Total: ~150 min (2h 30m) — 33% faster

The gains are even greater when developing independent domains in parallel:

Parallel execution (independent modules):
  Auth module      [===========]                60 min
  Order module     [===============]            75 min  ← longest task sets the total
  Notification     [========]                   45 min
  ─────────────────────────────────
  Total: 75 min (vs. 180 min sequential → 58% faster)

How It Differs from Agent Tool

Claude Code's built-in Agent Tool can run sub-agents too, but has fundamental limitations:

Feature	Agent Tool	cmux-agent-teams
Execution model	Sub-tasks within a single process	Separate Claude instances in independent terminals
Inter-agent communication	Not possible (results only)	Real-time P2P messages + signals
Intermediate result sharing	Not possible	Instant sharing via outbox/inbox
Progress monitoring	Wait until completion	Real-time monitoring with read-screen
Agent autonomy	Limited	Independent execution, own tool access
Plugin support	Not available	Each agent can load its own plugins

Works with Any Project

cmux-agent-teams makes no assumptions about your framework or project structure.

• Spring Boot, React, Next.js, Go, Python, Ruby — any stack works
• Drop it into legacy projects without changes
• Auto-detects CLAUDE.md, package.json, build.gradle and injects context into agents
• Works with custom roles even without Expert skill plugins

---

Requirements

Requirement	Version	Check
cmux	latest	cmux version
Claude Code	latest	claude --version
bash	4.0+	bash --version
jq	1.6+	jq --version

Install cmux at https://cmux.dev

---

Installation

Option 1: Remote Install from GitHub (Recommended)

Install directly from GitHub through Claude Code's plugin marketplace system. No need to clone or manage files manually — updates are picked up automatically.

# 1. Register the GitHub repo in the marketplace
/plugin marketplace add hungrytech/cmux-agent-teams

# 2. Install the plugin
/plugin install cmux-agent-teams@cmux-agent-teams

Or directly from the CLI:

claude plugin marketplace add hungrytech/cmux-agent-teams
claude plugin install cmux-agent-teams@cmux-agent-teams

Specifying Scope