From tmux-subagent
Launch and manage independent Claude sub-agents in tmux sessions with isolated configurations, custom tool permissions, and real-time monitoring capabilities
npx claudepluginhub nsheaps/ai-mktpl --plugin tmux-subagentThis skill is limited to using the following tools:
Launch independent Claude sub-agents that run in parallel tmux sessions with their own configurations, tool permissions, and plugin environments.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Analyzes BMad project state from catalog CSV, configs, artifacts, and query to recommend next skills or answer questions. Useful for help requests, 'what next', or starting BMad.
Launch independent Claude sub-agents that run in parallel tmux sessions with their own configurations, tool permissions, and plugin environments.
Use tmux sub-agents when you need:
/tmp/claude-subagent/<session-name>/.claude/ configuration# Launch with a prompt
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh \
--name "refactor-task" \
--prompt "Refactor the authentication module in src/auth/ to use async/await"
# Launch with prompt from file
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh \
--name "docs-update" \
--prompt-file /path/to/task-description.md
# Read-only sub-agent (no Write, Edit, or Bash)
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh \
--name "code-review" \
--denied-tools "Write,Edit,Bash" \
--prompt "Review src/api/ for security issues and report findings"
# Limited tools
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh \
--name "analyzer" \
--allowed-tools "Read,Grep,Glob" \
--prompt "Analyze the codebase structure and create a report"
# Different working directory
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh \
--name "other-project" \
--work-dir /path/to/other/project \
--prompt "Update dependencies in this project"
# With additional plugins
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh \
--name "with-plugins" \
--plugins "/path/to/plugin1,/path/to/plugin2" \
--prompt "Use the custom plugins to complete this task"
# Skip permission prompts (dangerous!)
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh \
--name "autonomous" \
--permission-mode dontAsk \
--prompt "Complete this task without asking for permissions"
{
"name": "complex-task",
"workDir": "/path/to/project",
"prompt": "Implement the feature described in docs/spec.md",
"allowedTools": "Read,Write,Edit,Glob,Grep",
"deniedTools": "Bash",
"plugins": "/path/to/plugin1,/path/to/plugin2",
"permissionMode": "allowedTools"
}
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh --config task-config.json
# Source helpers for function access
source ${CLAUDE_PLUGIN_ROOT}/scripts/tmux-helpers.sh
# List all active sub-agent sessions
subagent_list
# Get session status
subagent_status refactor-task
# View recent output (last 50 lines)
subagent_output refactor-task 50
# View full scrollback history
subagent_history refactor-task
# Send a message to the sub-agent
subagent_send refactor-task "Also update the tests please"
# Send interrupt (Ctrl-C)
subagent_interrupt refactor-task
# List sessions
tmux list-sessions
# View current pane content
tmux capture-pane -t refactor-task -p
# View last 100 lines
tmux capture-pane -t refactor-task -p -S -100
# Attach to session interactively
tmux attach -t refactor-task
# Send keys to session (C-m sends Enter key)
tmux send-keys -t refactor-task "your message here" C-m
# Alternative: separate Enter argument
tmux send-keys -t refactor-task 'your message here'
tmux send-keys -t refactor-task Enter
# Kill a specific session
source ${CLAUDE_PLUGIN_ROOT}/scripts/tmux-helpers.sh
subagent_kill refactor-task
# Kill all sub-agent sessions
subagent_kill_all
# Or directly with tmux
tmux kill-session -t refactor-task
# Wait for session to complete (blocks)
subagent_wait refactor-task
# Wait with timeout (seconds)
subagent_wait refactor-task 1800 # 30 minute timeout
# Get workspace path
subagent_workspace refactor-task
# Output: /tmp/claude-subagent/refactor-task
# Check workspace settings
cat /tmp/claude-subagent/refactor-task/.claude/settings.json
Give sub-agents well-defined, scoped tasks:
# Good: Specific, bounded task
--prompt "Refactor the UserService class in src/services/user.ts to use dependency injection. Update tests accordingly."
# Bad: Vague, unbounded
--prompt "Make the code better"
Match tools to the task:
# Code review: Read-only
--denied-tools "Write,Edit,Bash"
# Documentation: Write but no execute
--denied-tools "Bash"
# Analysis: Read + search only
--allowed-tools "Read,Grep,Glob"
For autonomous tasks, periodically check progress:
# Quick status check
tmux capture-pane -t session-name -p | tail -20
# Full output to file for analysis
tmux capture-pane -t session-name -p -S - > /tmp/session-output.txt
# Kill and clean up
subagent_kill session-name
# Or manually clean workspace
rm -rf /tmp/claude-subagent/session-name
# Check if tmux is installed
which tmux
# Check for existing session with same name
tmux has-session -t session-name && echo "exists"
# Check workspace creation
ls -la /tmp/claude-subagent/
# Check if iTerm is running
pgrep -x iTerm2
# Try manual attachment
tmux attach -t session-name
# Check AppleScript permissions in System Preferences > Security > Privacy > Automation
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
This is equivalent to pressing Escape in the teammate's pane, which interrupts the current turn without killing the session.
# Check settings.json has correct allowed directories
cat /tmp/claude-subagent/session-name/.claude/settings.json | jq '.permissions'
# Verify work directory exists
ls -la $(jq -r '._workDir' /tmp/claude-subagent/session-name/.claude/settings.local.json)
# Check applied tool restrictions
cat /tmp/claude-subagent/session-name/.claude/settings.json | jq '.permissions.allow.tools'
cat /tmp/claude-subagent/session-name/.claude/settings.json | jq '.permissions.deny.tools'
# Launch multiple sub-agents for different modules
for module in auth api database; do
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh \
--name "refactor-$module" \
--prompt "Refactor src/$module/ to use TypeScript strict mode" \
--no-iterm
done
# Monitor all
for session in $(tmux list-sessions -F "#{session_name}" | grep "^refactor-"); do
echo "=== $session ==="
tmux capture-pane -t "$session" -p | tail -5
done
# Read-only review agent
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh \
--name "security-review" \
--denied-tools "Write,Edit,Bash" \
--prompt "Review all files in src/ for security vulnerabilities. Write findings to /tmp/security-review.md using the allowed Read tool to read files."
# Agent with test plugins, no access to modify production code
${CLAUDE_PLUGIN_ROOT}/scripts/launch-subagent.sh \
--name "plugin-test" \
--work-dir /tmp/test-workspace \
--plugins "/path/to/experimental-plugin" \
--prompt "Test the experimental plugin features"
--permission-mode dontAsk only for trusted, well-defined tasks/tmp/The plugin automatically opens an iTerm tab attached to the tmux session. This allows you to:
To disable: --no-iterm
Session names are sanitized (dots, colons, slashes become dashes). If no name is provided, a timestamp-based name is generated: subagent-<timestamp>