Tmux Lanes
Manage a multi-agent workspace as a set of tmux panes, each one a lane with a known state, a known assignment, and a clean lifecycle.
What this is
When you're running multiple AI agents in parallel, each in its own tmux pane, the workspace itself becomes an instrument that needs tuning. Which pane is active? Which is stale? Which is ready for new work? What's each one doing?
This skill turns the tmux window into a managed workspace: visible state, deliberate allocation, clean handoffs.
Executable sub-skills: lanes-status for a quick status view, lanes-plan for allocation proposals.
When to use it
- Any workflow where multiple agents run in parallel tmux panes
- When you've lost track of which pane is doing what
- Before allocating new work across lanes
- When stale sessions are cluttering the workspace
The pattern
Status view
Probe the workspace and present the full picture. Three commands give you everything:
# Inventory: index, size, process, PID
tmux list-panes -t <window> -F '#{pane_index} #{pane_width}x#{pane_height} #{pane_current_command} #{pane_pid}'
# Titles: what each pane is named
tmux list-panes -t <window> -F '#{pane_index} #{pane_title}'
# State: last few lines of each pane's output
for i in 0 1 2; do echo "=== Pane $i ===" && tmux capture-pane -t <window>.$i -p | tail -5; done
From the captured output, classify each pane:
- Active: an agent is running and producing output
- Idle/Stale: an agent session is open but waiting for input (e.g. INSERT mode with no recent activity)
- Shell: no agent running, clean prompt ready for work
- Unknown: something else is running
Render the result as a table:
┌─────────────────┬────────┬──────────────────────┬──────────────────────────────────────────┐
│ Pane │ Size │ Title │ Status │
├─────────────────┼────────┼──────────────────────┼──────────────────────────────────────────┤
│ 0 (left) │ 162x82 │ "meta" │ Us — meta, active │
├─────────────────┼────────┼──────────────────────┼──────────────────────────────────────────┤
│ 1 (upper-right) │ 153x40 │ "Feature work" │ Stale — last session's agent, idle │
├─────────────────┼────────┼──────────────────────┼──────────────────────────────────────────┤
│ 2 (lower-right) │ 153x41 │ "Research" │ Shell — ready for new agent │
└─────────────────┴────────┴──────────────────────┴──────────────────────────────────────────┘
The goal: one glance tells you the state of the whole workspace.
Allocation
Read the work queue (task list, active items, session plan), count available lanes, and propose assignments:
Pane: 0 (left)
Assignment: Meta (us)
Work: Orchestration, review, decisions
────────────────────────────────────────
Pane: 1 (upper-right)
Assignment: Coding Agent A
Work: Implement auth middleware — tests + integration (item 1, the complex one)
────────────────────────────────────────
Pane: 2 (lower-right)
Assignment: Coding Agent B
Work: API endpoint handlers for items 2-4 (same pattern repeated)
For complex layouts, a spatial view helps the operator see the whole board:
┌─────────────────────────────┬─────────────────────────────┐
│ │ │
│ META (me) │ CODING AGENT A │
│ Upper Left │ Upper Right │
│ │ │
│ Coordination, reviews, │ Auth middleware + tests │
│ architecture decisions │ (item 1, the complex one) │
│ │ │
│ Always present. │ Long-lived. Spin up now, │
│ Light context. │ independent, no blockers. │
│ │ │
├─────────────────────────────┼─────────────────────────────┤
│ │ │
│ CODING AGENT B │ FLEX │
│ Lower Left │ Lower Right │
│ │ │
│ API handlers for items │ Available for: │
│ 2-4 (same pattern) │ - Code reviews as PRs │
│ │ come in │
│ Depends on A's middleware │ - Ad hoc investigation │
│ landing first. │ │
│ │ Spin up when needed, │
│ │ idle otherwise. │
│ │ │
└─────────────────────────────┴─────────────────────────────┘
Sequencing logic:
- Upper Right (A): Spin up now. Independent, no blockers.
- Lower Left (B): Spin up after A's middleware lands. Same agent
can continue or fresh session.
- Lower Right: Hold in reserve for reviews as A and B produce PRs.
Critical path: A middleware → B handlers → integration tests.
Everything else is parallel enrichment.
Consider:
- Which harness is appropriate (some tasks favor one tool over another)
- Whether a pane's existing context is useful for the new task
- Whether to start a fresh session or continue an existing one
- The operator makes the final call on assignments
Prompt drafting
When a lane gets an assignment, draft a deployment prompt:
- Scoped to exactly this agent's task, no more
- Includes the context the agent needs (relevant files, current state, constraints)
- States what "done" looks like
- States what the agent should not touch (other agents' work, shared state files)
- Matches the prompt style to the agent type (research, planning, coding)
Cleanup
Recycle stale panes when the workspace needs clearing:
- For each idle/stale pane: terminate the old agent session gracefully
- Leave clean shell prompts ready for new agents
- Recycle panes rather than destroying and recreating them: the pane layout is part of your workspace ergonomics, and rebuilding it is wasted motion
Anti-patterns
- Untracked lanes. Agents running without anyone knowing what they're working on. Every lane should have a known assignment.
- Stale accumulation. Letting finished sessions sit open. They add visual noise and tempt you to reuse context that's probably degraded.
- Over-packing. Too many agents in too many panes. The failure mode is specific: the meta-agent's own context fills with status-tracking, lanes start duplicating work because nobody can keep the full picture in view, and you spend more time coordinating than producing. Use the minimum number of concurrent agents that the work actually requires.
- Manual-only tracking. Keeping lane state only in your head. Write it down. A state file that lists pane assignments is cheap insurance against losing track.