Tmux for AI Agents: Templates 2026

Tmux for AI Agent Orchestration: Parallel Development Patterns 2026

Tmux, originally released in 2007 as a client-server terminal multiplexer, is now the go-to tool for mid-to-senior developers managing 4–8 parallel AI agents like Claude Code, Codex CLI, or Gemini CLI. Instead of relying on GUI wrappers, teams use pure bash scripts and tmux windows—each dedicated to one agent or git worktree. This approach eliminates context loss, git conflicts, and cognitive overload. We explore three proven patterns from Hacker News: Feature Designs, agent forking, and worktree integration.

The Feature Designs Pattern: Markdown Plans + Executor Agents

Manuel Schipper (Staff AI Engineer, Snowflake) delegates 90% of coding to AI agents using structured Markdown specs called Feature Designs (FD). Each tmux window plays a distinct role:

• Planner: generates FDs from problem statements.
• Worker: implements features based on FDs.
• PM: manages the backlog.

FDs are numbered (e.g., FD-001…), stored in docs/features/, and follow this structure:

• Problem: clear description of the issue.
• Solutions: multiple options with trade-offs (pros/cons).
• Chosen Solution: implementation plan and file list.
• Verification: steps to validate correctness.

Example FD-051:

FD-051: Multi-label document classification
Status: Open
Priority: Medium
Effort: Medium
Impact: Better recall

## Problem
Incoming documents get a single category label, but many span multiple topics.

## Solution
1. LLM confidence scores per category.
2. Accept >0.90.
3. Second pass for 0.50–0.90.
4. Store with scores.

## Files
- src/classify/multi_label.py
- src/classify/prompts.py
- sql/01_schema.sql

## Verification
1. Run on staging.
2. Health checks.
3. Spot-check.

Lifecycle: Planned → Design → Open → In Progress → Pending Verification → Complete. Automation via six slash commands:

• /fd-new: create a new FD.
• /fd-status: view an index of all FDs.
• /fd-explore: load context into current session.
• /fd-deep: launch four parallel agents (algorithms/structure/increment/environment).
• /fd-verify: proofread and commit changes.
• /fd-close: archive completed FDs.

/fd-deep leverages test-time compute principles by running four agents simultaneously to generate ideas. Over months, teams produce 300+ FDs. Initialization: /fd-init sets up the full infrastructure.

Trade-off: agents compress context, losing fine details—Schipper manually writes checkpoints in Markdown to preserve clarity.

Agent Forking Pattern: Context-Specific Forks

Kaushik Gopal (Principal Engineer, Instacart) proposes a no-planning fork model. In the current session, capture the pane buffer (tmux capture-pane), wrap it in <context>, and launch it in a new window.

The bash script is minimal and tool-agnostic: fork from Claude to Gemini for diagram generation. Interactively, you copy needed content back manually.

Pros:

• Low overhead—fork only when needed.
• Cross-agent workflow: Codex → Claude → Gemini.

Cons:

• No auto-merge capability.
• Long forks (>1 hour) risk desync with main branch.

Use case: exploring tangential hypotheses or testing features in parallel. Script available on Gist—just 20 lines.

Git Worktree + Tmux: Directory Isolation

Syo Ito solves git conflicts by assigning one git worktree per agent and one tmux window per worktree. Window names match worktree names.

Avoid pane chaos: don’t split panes by worktree. Use one window per worktree, with panes for shell and Vim.

Utility tool kage: kage feat-x creates a worktree, a tmux window, and launches Claude Code.

Example agent-worker script:

#!/usr/bin/env bash
set -euo pipefail
WORKTREE_NAME="${1:?}"
FD_NUMBER="${2:?}"
WT_PATH="$(git rev-parse --show-toplevel)/../${WORKTREE_NAME}"

git worktree add "$WT_PATH" -b "feat/${WORKTREE_NAME}"
tmux new-window -n "$WORKTREE_NAME" -c "$WT_PATH" \
  "claude --permission-mode acceptEdits 'implement FD-${FD_NUMBER}'"

Minimal tmux.conf for Agents

# Prefix C-a
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# Numbering starts at 1
set -g base-index 1
setw -g pane-base-index 1

# Mouse support
set -g mouse on

# History size
set -g history-limit 50000

# Vim-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

set -g renumber-windows on

Key Takeaways

• Max 4–8 agents: Beyond that, focus degrades and output quality drops.
• Git worktree required: Essential for avoiding conflicts with 3+ agents.
• One window per agent: Avoid pane sprawl that breaks navigation.
• Manual Markdown checkpoints: Mitigate context compaction loss.
• Bash + Tmux: Zero dependencies, fully tool-agnostic.

— Editorial Team