claude-cmux-skill

Orchestrate independent Claude Code sessions in cmux — split panes, monitor agents, automate browsers, coordinate parallel work

Running multiple AI agents but can't see what they're doing?
That's what happens when your terminal wasn't built for agent orchestration.

Installation • Usage • The Problem • How It Works • Examples

This plugin teaches Claude Code how to use cmux — a native macOS terminal built for AI coding agents. Use /cmux to spawn parallel Claude Code sessions in split panes, monitor agent output, automate browsers, manage notifications, and coordinate multi-agent workflows.

Installation

Platform	How to install
Claude Code	claude plugin marketplace add ph3on1x/claude-cmux-skill claude plugin install claude-cmux-skill

Note

Requires cmux (macOS 14.0+) and Claude Code CLI. Use /cmux to invoke the skill inside a cmux terminal.

When to Use What

You're thinking...	Use	What happens
"I need three agents working in parallel"	/cmux Spin up 3 agents to research X, Y, Z	Creates split panes, launches independent Claude Code sessions, monitors output via read-screen, coordinates with sync tokens
"What's my other agent doing?"	/cmux Check agent progress in surface:5	Reads terminal output from any surface without switching to it, reports status
"I need to test this in a browser"	/cmux Open browser and test the login flow	Opens browser surface, snapshots for element refs, interacts via click/fill — no CSS selectors
"Notify me when the build finishes"	/cmux Notify me when the build finishes	Uses cmux notify (in-app) or osascript (system-level) based on context
"I need agents to share data"	/cmux Share API findings with the test agent	Stores results in named buffers, signals completion with wait-for tokens

The Problem

AI coding agents are powerful individually. But when you need multiple agents working in parallel:

• No visibility — you can't see what other agents are doing without switching panes manually
• No coordination — agents can't signal completion or share results with each other
• No orchestration — splitting work across panes, monitoring progress, and collecting results requires manual effort

How It Works

Invoke with /cmux inside a cmux terminal. The skill uses progressive disclosure — core concepts load when /cmux is invoked, while detailed references load only when Claude needs them.

claude-cmux-skill/
├── .claude-plugin/
│   ├── plugin.json              # Plugin metadata
│   └── marketplace.json         # Marketplace catalog
├── hooks/
│   └── hooks.json               # Lifecycle hooks (SessionStart, Stop, Notification)
└── skills/
    └── cmux/
        ├── SKILL.md             # /cmux skill
        └── references/
            ├── orchestration.md       # Multi-agent patterns
            ├── browser-automation.md  # Full browser API
            ├── notifications.md       # Notification systems
            └── complete-cli.md        # Complete CLI catalog

Key Capabilities

Capability	What Claude can do
Agent Orchestration	Split panes, launch independent Claude Code sessions, monitor output via read-screen, coordinate with wait-for sync tokens, track progress in sidebar
Terminal I/O	Read terminal output from any surface, pipe through commands, share data between panes via named buffers
Browser Automation	Snapshot-based browser control with element refs — click, fill, type using refs like e3 instead of CSS selectors
Sidebar Metadata	Status pills, progress bars, and log entries for real-time orchestration visibility
Notifications	Context-aware selection between in-app (cmux notify) and system-level (osascript) alerts
Workspace Management	Create, switch, rename, and close workspaces with optional startup commands

Real-World Scenarios

Parallel feature implementation

You: /cmux Implement auth and payments modules in parallel

Claude splits two panes, launches an independent session in each:
  surface:5 → "claude 'implement auth module'"
  surface:6 → "claude 'implement payments module'"

Claude monitors both via read-screen, updates sidebar progress,
and collects results when sessions finish.

Browser testing with agent oversight

You: /cmux Open the app in a browser and verify the login flow works

Claude opens a browser surface, navigates to localhost:3000,
snapshots the page for element refs, fills the login form,
clicks submit, waits for navigation, and re-snapshots to
verify the dashboard loaded.

Multi-agent coordination with data sharing

You: /cmux Research the API, then have another agent write tests based on findings

Agent 1 explores the API, stores findings in a named buffer:
  cmux set-buffer --name "api-findings" "endpoints: /users, /orders..."

Agent 1 signals completion:
  cmux wait-for --signal api-research-done

Agent 2 was waiting for the signal, retrieves the buffer,
and writes tests based on the shared findings.

Acknowledgments

• cmux — The native macOS terminal for AI coding agents
• Anthropic — Claude Code and the Agent Skills standard

License

MIT