Skip to content

README.md

Latest commit

 

History

History
236 lines (174 loc) · 6.47 KB

README.md

File metadata and controls

236 lines (174 loc) · 6.47 KB

Tmux Sub-Agent Plugin

Launch independent Claude sub-agents in tmux sessions with isolated configurations, custom tool permissions, and real-time monitoring.

Features

  • Parallel Execution: Run multiple Claude instances simultaneously
  • Tool Isolation: Configure allowed/denied tools per sub-agent
  • Plugin Isolation: Install plugins without affecting your main session
  • Configuration Inheritance: Sub-agents inherit your project's .claude/ config
  • iTerm Integration: Automatically opens macOS iTerm tabs attached to sessions
  • Real-time Monitoring: View output, send messages, and manage sessions

Installation

See Installation Guide for all installation methods.

Quick Install

# Via marketplace (recommended)
# Follow marketplace setup: ../../docs/manual-installation.md

# Or via GitHub
claude plugins install github:nsheaps/ai-mktpl/plugins/tmux-subagent

# Or locally for testing
cc --plugin-dir /path/to/plugins/tmux-subagent

Requirements

  • tmux: Must be installed (brew install tmux on macOS)
  • jq: Recommended for config file parsing (brew install jq)
  • iTerm2: Optional, for automatic tab attachment on macOS

Quick Start

Using the Slash Command

/subagent Refactor the authentication module to use async/await
/subagent Review src/api/ for security issues --readonly
/subagent --list
/subagent --output my-session
/subagent --kill my-session

Using the Launch Script

# Basic launch
./scripts/launch-subagent.sh --name "my-task" --prompt "Your task here"

# With tool restrictions
./scripts/launch-subagent.sh \
  --name "read-only-review" \
  --denied-tools "Write,Edit,Bash" \
  --prompt "Review the codebase for issues"

# With additional plugins
./scripts/launch-subagent.sh \
  --name "with-plugins" \
  --plugins "/path/to/plugin1,/path/to/plugin2" \
  --prompt "Use custom plugins for this task"

How It Works

  1. Workspace Creation: Creates /tmp/claude-subagent/<session-name>/
  2. Config Copy: Copies your project's .claude/ configuration
  3. Permission Setup: Adds original project as allowed directory
  4. Tool Config: Applies specified tool restrictions
  5. Plugin Install: Symlinks additional plugins to temp workspace
  6. Session Launch: Starts Claude in detached tmux session
  7. iTerm Tab: Opens attached iTerm tab (macOS only)

Configuration Options

Option Description Default
--name Session name subagent-<timestamp>
--work-dir Working directory Current directory
--prompt Initial prompt None
--prompt-file File containing prompt None
--allowed-tools Comma-separated allowed tools All standard tools
--denied-tools Comma-separated denied tools None
--plugins Comma-separated plugin paths None
--permission-mode allowedTools or dontAsk allowedTools
--model Model to use Inherited
--no-iterm Don't open iTerm tab Opens tab
--attach Attach after creation Detached
--config JSON config file None

Monitoring Sessions

Using Helper Functions

# Source helpers
source ./scripts/tmux-helpers.sh

# List sessions
subagent_list

# View output
subagent_output my-session 50

# Send message
subagent_send my-session "Please also update the tests"

# Kill session
subagent_kill my-session

Direct Tmux Commands

# List all sessions
tmux list-sessions

# View pane content
tmux capture-pane -t my-session -p

# Attach interactively
tmux attach -t my-session

# Send keys
tmux send-keys -t my-session "message" Enter

File Structure

tmux-subagent/
├── .claude-plugin/
│   └── plugin.json           # Plugin metadata
├── commands/
│   └── subagent.md           # /subagent slash command
├── skills/
│   └── tmux-subagent/
│       └── SKILL.md          # Comprehensive skill docs
├── scripts/
│   ├── launch-subagent.sh    # Main launch script
│   ├── attach-iterm.applescript  # iTerm integration
│   └── tmux-helpers.sh       # Management utilities
└── README.md

Use Cases

Parallel Refactoring

for module in auth api database; do
  ./scripts/launch-subagent.sh \
    --name "refactor-$module" \
    --prompt "Refactor src/$module/ to use TypeScript strict mode" \
    --no-iterm
done

Isolated Code Review

./scripts/launch-subagent.sh \
  --name "security-review" \
  --denied-tools "Write,Edit,Bash" \
  --prompt "Review all files for security vulnerabilities"

Plugin Testing

./scripts/launch-subagent.sh \
  --name "test-new-plugin" \
  --work-dir /tmp/test-project \
  --plugins "/path/to/experimental-plugin" \
  --prompt "Test the new plugin features"

Security Notes

  • Permission Mode: Use dontAsk only for trusted, well-defined tasks
  • Tool Restrictions: Always limit tools to what's actually needed
  • Work Directory: Sub-agents only access the specified directory
  • Workspace: Each session has isolated config in /tmp/
  • Cleanup: Kill sessions and remove workspaces when done

Troubleshooting

tmux not found

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

iTerm tab doesn't open

  1. Check iTerm2 is running
  2. Verify AppleScript permissions in System Preferences > Security > Privacy > Automation
  3. Use --no-iterm and attach manually: tmux attach -t session-name

Agent unresponsive (stuck mid-turn)

If a teammate agent is stuck mid-turn and not processing messages, send the ESC key via tmux to interrupt its current turn and allow pending messages to propagate:

tmux send-keys -t <pane-id> Escape

Sub-agent can't access files

Check the workspace settings:

cat /tmp/claude-subagent/session-name/.claude/settings.json | jq '.permissions'

Session name conflicts

# Check existing sessions
tmux list-sessions

# Use unique name
./scripts/launch-subagent.sh --name "unique-name-$(date +%s)" --prompt "..."

License

MIT
⚡