tmux-subagent

Launch independent Claude sub-agents in isolated tmux sessions.

3|1|Updated Dec 3, 2025
One-click install
npx skills add https://github.com/nsheaps/ai-mktpl --skill tmux-subagent
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: tmux-subagent
Source: https://github.com/nsheaps/ai-mktpl/tree/main/plugins/tmux-subagent/skills/tmux-subagent
Command: npx skills add https://github.com/nsheaps/ai-mktpl --skill tmux-subagent

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Coordinate and run multiple independent Claude instances in parallel while keeping each agent isolated with its own configuration, tool permissions, and plugin environment to avoid interference, accidental modifications, or permission escalation.

Core Features & Use Cases

  • Parallel, isolated agents: Launch multiple tmux-backed Claude sub-agents to work on different aspects of a project simultaneously without sharing state.
  • Permission and plugin isolation: Apply allow/deny tool rules per session and install session-scoped plugins to safely test or restrict capabilities.
  • Monitoring and lifecycle controls: Create temporary per-session workspaces, monitor output via tmux or iTerm integration, send messages or interrupts, and clean up sessions when finished.
  • Use Case: Run a read-only security review agent against src/ while a separate refactor agent makes changes in a sandboxed workspace.

Quick Start

Launch a tmux sub-agent named refactor-task to refactor the authentication module in src/auth and report the proposed changes.

Frequently Asked Questions about tmux-subagent

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run parallel Claude instances without them interfering with each other?

To run parallel Claude instances without interference, you can launch isolated sub-agents in separate tmux sessions. This creates independent environments with per-session temporary workspaces, preventing accidental modifications and state sharing between agents.

What is the best way to test Claude plugins in an isolated environment?

Testing Claude plugins in an isolated environment is best achieved by launching a sub-agent in a dedicated tmux session. This approach allows you to install session-scoped plugins and apply specific tool permission rules without risking your main configuration.

Can I enforce different tool permissions for each Claude agent?

Yes, you can enforce different tool permissions for each Claude agent by applying allow and deny rules per tmux session. This ensures each isolated sub-agent operates within its defined capability boundaries.

How do I monitor and control long-running background AI tasks in tmux?

You can monitor and control long-running background AI tasks in tmux by using exposed tmux and iTerm monitoring utilities. These tools allow you to track output, send messages or interrupts, and clean up sessions when tasks are finished.

Does tmux-subagent work with iTerm for monitoring sub-agents?

Yes, tmux-subagent works with iTerm by exposing specific iTerm integration utilities for monitoring and control. You can use these alongside tmux commands to observe sub-agent output and manage session lifecycles.

Why should I use isolated tmux sessions for AI automation workflows?

You should use isolated tmux sessions for AI automation workflows to prevent permission escalation and state interference. This method provides each agent with its own configuration and workspace, ensuring safe parallel processing.