cmux-claude-agents

Spawn Claude Code agents as visible cmux panes instead of hidden subprocesses.

When Claude tries to use the Agent tool inside cmux, the hook intercepts it and redirects to a real split pane — so you can see what every agent is doing.

Prerequisites

• cmux installed and running
• Claude Code CLI (claude)
• jq (recommended: brew install jq)

Install

git clone https://github.com/Th3Sp3ct3R/cmux-claude-agents.git
cd cmux-claude-agents
./install.sh /path/to/your/project

This copies into your project's .claude/ directory:

• hooks/cmux-spawn-agent.sh — spawns an agent in a cmux pane
• hooks/cmux-agent-intercept.sh — PreToolUse hook that redirects Agent calls
• commands/spawn.md — teaches Claude the /spawn command
• settings.json — wires up the hook (merges if exists)

Usage

# Start a cmux session
cmux new-session --name work

# Open your project and start Claude
cd /path/to/your/project
claude

# Spawn agents in visible panes
/spawn researcher "Analyze the auth system"
/spawn coder "Fix the login bug" --model opus
/spawn researcher "Find patterns" + coder "Implement fix" + tester "Write tests"

How it works

1. Hook intercepts — when Claude calls the Agent tool, cmux-agent-intercept.sh checks if you're in cmux
2. Read-only agents pass through — Explore, Plan, claude-code-guide stay as hidden subagents (they can't edit files)
3. Execution agents redirect — coder, tester, researcher etc. get blocked with a message to use /spawn
4. /spawn creates panes — each agent runs as a full Claude Code session in its own cmux split
5. Notifications — cmux sends a notification when each agent finishes

Flags

Flag	Description
--name	Agent name (shows in cmux tab)
--prompt	Task description
--prompt-file	Read prompt from file
--direction	Split: right, down, left, up
--model	haiku, sonnet, opus
--yes	Autonomous (skip permissions)
--print	Single-shot text, no tools
--no-notify	Skip notification

Test

./test.sh

Runs basic validation: checks files exist, are executable, parse args correctly, and the intercept hook produces valid JSON.