Stats
Links
Categories
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