tmux-orchestrator

tmux-orchestrator

Other tools give you an agent framework. This gives you tmux windows.

A Claude Code plugin for managing multi-agent teams in tmux. Spawn Claude Code agents in isolated windows with their own context, git worktrees, and task injection. Two-way communication via tmux send-keys. No daemons, no APIs, no polling — the window list is the registry.

What You Get

• Two skills: /tmux-orchestrator:orchestrate (reactive management) and /tmux-orchestrator:persistent (always-on orchestrator)
• Scripts: spawn, kill, message, list, watch, compact, reconcile — all bash, all tmux
• Agent templates: ephemeral, coder, persistent, researcher
• CLAUDE.md injection: coders get task context and completion protocols baked in
• Worktree isolation: each coder gets its own branch — no merge conflicts during parallel work
• Auto-approval: watch_agents unblocks stuck permission prompts across all agent panes

Installation

From GitHub (now)

# In your Claude Code settings.json
{
  "enabledPlugins": {
    "tmux-orchestrator": {
      "source": "github:twaldin/tmux-orchestrator"
    }
  }
}

Local development

{
  "enabledPlugins": {
    "tmux-orchestrator@local": {
      "source": "local:/path/to/tmux-orchestrator"
    }
  }
}

Standalone (without plugin system)

Add to your shell profile:

export TMUX_ORCHESTRATOR_HOME="$HOME/tmux-orchestrator"
export PATH="$TMUX_ORCHESTRATOR_HOME/scripts:$PATH"

Note: standalone mode only adds the scripts to PATH. The hooks (auto-approval on Stop, completion reminder) and slash commands won't be active unless you also add the plugin to settings.json as shown above.

Requirements

• tmux
• Claude Code CLI (claude)
• bash
• git and gh (for spawn_coder)

Quick Start

1. Start a tmux session
2. Launch Claude Code
3. Run /tmux-orchestrator:orchestrate

You're now an orchestrator. Spawn your first agent:

spawn_teammate researcher ~/my-project \
  --task "Research the top 3 Rust async runtimes. Return findings via message_parent."

When it's done, it messages you: [RESEARCHER]: Done. Findings in research-rust-async.md.

Then: kill_teammate researcher

Scripts

All scripts live in scripts/ and are added to spawned agents' PATH automatically.

Script	Usage
spawn_teammate	Spawn agent in named tmux window
kill_teammate	Kill agent, restore CLAUDE.md, close window
send_message	Send message to agent (orchestrator → agent)
message_parent	Send message to orchestrator (agent → orchestrator)
list_teammates	List all agent windows with status
watch_agents	Auto-approve stuck permission prompts
compact_self	Agent self-compaction: write state, /clear, resume
spawn_coder	Convenience: worktree + GitHub issue context
agent_status	Show context window usage and liveness for all agents
capture_pane	Capture recent output from an agent's pane
reconcile_agents	Detect dead agents; --fix respawns dead persistent agents

spawn_teammate

spawn_teammate <name> <dir> [--model M] [--lifecycle L] [--task T] [--worktree] [--type coder]

• --model opus|sonnet|haiku — model tier (default: sonnet)
• --lifecycle ephemeral|persistent — whether agent exits when done (default: ephemeral)
• --task "..." — first message sent to agent
• --worktree — create git worktree for file isolation
• --type coder — add PR workflow + git rules to injection

spawn_coder

spawn_coder <issue_number> [--dir <project_dir>] [--model M]

Fetches GitHub issue, creates worktree, spawns coder with full context.

Skills

/tmux-orchestrator:orchestrate

The core product. Teaches you:

• When to spawn agents vs when to just do the work yourself
• How to use all the scripts
• Two-way communication patterns
• Lifecycle management (kill, compact, re-task)
• Parallel work patterns

/tmux-orchestrator:persistent

Advanced. Teaches you how to run as an always-on orchestrator:

• Directory setup (state.md, tasks.md, crons.md)
• Self-compaction when context fills
• Heartbeat crons
• Task queue and proactive work loop
• Spawning persistent sub-agents

Agent Types

Ephemeral

Default. Spawned for one task, exits when done. Gets completion protocol injection (message_parent + /exit).

spawn_teammate analyst ~/data \
  --task "Analyze sales-q1.csv. Write findings to analysis.md. message_parent when done."

Coder (--type coder)

Ephemeral + PR workflow + git rules. Designed for worktree-isolated code changes.

spawn_teammate fix-auth ~/project --type coder --worktree \
  --task "Fix the JWT expiry bug in auth/token.ts. Tests in auth/token.test.ts."

Persistent (--lifecycle persistent)

Long-running. Has its own permanent directory with state.md and crons.md. Self-compacts independently.