primeline-ai/claude-tmux-orchestration
Claude Code tmux orchestration — spawn full AI sessions as parallel workers with heartbeat monitoring and file-based coordination
Platform-specific configuration:
{
"mcpServers": {
"claude-tmux-orchestration": {
"command": "npx",
"args": [
"-y",
"claude-tmux-orchestration"
]
}
}
}Add the config above to .claude/settings.json under the mcpServers key.
> Spawn full Claude Code sessions as workers — each with its own 1M context window, hooks, MCP servers, and compaction. Coordinate them through a bash heartbeat and file-based state.
[](https://primeline.cc/blog/tmux-orchestration) [](https://primeline.cc/guide)
---
Sub-agents in Claude Code run inside your current session. They work for quick searches and code reviews, but three constraints make them unusable for complex work:
| Constraint | Sub-Agent (Tier 2) | tmux Worker (Tier 3) | |---|---|---| | Turn budget | ~25 tool calls max | Unlimited (own session) | | Hooks & MCP | No access | Full access | | Context window | Shares parent (~41K overhead each) | Own 1M context window | | Compaction | Not possible | Works normally | | Tools | Limited subset | Complete Claude Code instance |
tmux orchestration fills the gap between sub-agents (limited) and manual multi-tab (unstructured).
---
┌─────────────────────────────────────────────────────────┐
│ tmux Session │
│ │
│ ┌──────────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Window 0 │ │ Window 1 │ │ Window 2 │ │
│ │ Orchestrator │ │ Worker 1 │ │ Worker 2 │ ... │
│ │ (Claude Code)│ │ (Claude) │ │ (Claude) │ │
│ │ │ │ Sonnet │ │ Haiku │ │
│ └──────┬───────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └───────────┬───┴──────────────┘ │
│ │ │
│ _orchestrator/ Loading reviews...