tmux-agents

name: tmux-agents description: > Manage AI agent orchestration via the tmux-agents CLI. Use when the user wants to: spawn, list, kill, or interact with AI agents (Claude, Gemini, Codex, Aider, etc.); create and manage tasks on a kanban board with swim lanes; compose agent teams for collaborative work; run multi-stage pipelines (DAG execution); fan-out prompts to multiple agents simultaneously; configure runtimes (local tmux, SSH, Docker, Kubernetes); or check daemon health and status. Triggers on: agent management, task boards, kanban operations, AI orchestration, multi-agent workflows, pipeline execution, team coordination, tmux session management.

tmux-agents CLI Skill

Orchestrate 10-50+ concurrent AI agents across local tmux, remote SSH, Docker, and Kubernetes runtimes via the tmux-agents CLI.

Prerequisites

The daemon must be running before any commands work:

# Start daemon (background)
tmux-agents daemon start

# Or foreground for debugging
tmux-agents daemon run --debug

# Verify
tmux-agents health

Core Concepts

• Tasks = Agents: Tasks and agents are unified. A running task is an agent. agent list returns currently running tasks as agents. agent attach, agent kill, and agent output all accept task IDs. agent spawn creates a task + swim lane behind the scenes.
• Tasks: Work items on a kanban board (backlog/todo/doing/review/done). When started, a task spawns an AI agent in a tmux window.
• Swim Lanes: Isolated workstreams with their own working directory, provider, and WIP limits
• Teams: Named groups of agents working together
• Pipelines: Multi-stage DAG workflows where stages pass artifacts
• Runtimes: Execution environments (local, SSH, Docker, K8s) - all use tmux internally

Best Practices

1. Always Check Command Help First

Before using any command, check the help to understand exact syntax:

# Check available flags and their purpose
tmux-agents task submit --help
tmux-agents kanban create-lane --help
tmux-agents agent spawn --help

This prevents errors and ensures you use the right flags (e.g., --title for short titles vs the main argument for full descriptions).

2. Verify Resource Names/IDs Before Using Them

Before referencing lanes, agents, tasks, or teams, list them first to get exact names and IDs:

# ✓ BEFORE creating a task, check what lanes exist
tmux-agents kanban lanes --json
# Shows: {"id": "abc-123", "name": "backend"}

# ✓ Then use the EXACT name or (better) the ID
tmux-agents task submit "Fix bug" --lane backend  # by name
tmux-agents task submit "Fix bug" --lane abc-123  # by ID (more reliable)

# ✓ BEFORE sending to an agent, list agents
tmux-agents agent list --json
# Shows: {"id": "def-456", "role": "coder", ...}

# ✓ Then use the exact agent ID
tmux-agents agent send def-456 "Continue working"

Why this matters:

• Lane names can be similar (e.g., "tmux-agent" vs "tmux-agents")
• IDs are unique and never change
• Using wrong names creates orphaned tasks in non-existent lanes
• Typos in names fail silently or create unexpected behavior

Common Gotchas

1. Daemon Must Be Running

Every command except daemon start requires a running daemon. If you get connection errors:

tmux-agents daemon start
tmux-agents health   # verify it's healthy

2. Always Verify Lane Names Before Using Them

Lane names must match exactly. Typos silently create orphaned tasks:

# ✓ ALWAYS check first
tmux-agents kanban lanes --json

# ✓ Use the exact name or (better) the ID
tmux-agents task submit "Fix bug" --lane abc-123   # by ID (safest)
tmux-agents task submit "Fix bug" --lane backend   # by name (must match exactly)

# ❌ NEVER guess lane names
tmux-agents task submit "Fix bug" --lane back-end  # wrong if lane is "backend"

3. --start vs --auto-start Are Different

• --start: Immediately starts the task after submit (one-shot action)
• --auto-start: Sets a flag so the task auto-starts when lane WIP allows (persistent toggle, inherited from lane defaults)

Use --start for "submit and run now". Use --auto-start on lanes for autonomous workflows.

4. JSON Arguments Need Shell Quoting

Pipeline stages and team agents use JSON arguments. Always wrap in single quotes:

# ✓ Correct — single-quoted JSON
tmux-agents pipeline create "deploy" --stages '[{"name":"lint","role":"coder","prompt":"Run lint"}]'

# ❌ Wrong — shell will mangle unquoted JSON
tmux-agents pipeline create "deploy" --stages [{"name":"lint"}]

5. --description Flag Does Not Exist on task submit

The task description is the positional argument, not a flag:

# ✓ Correct
tmux-agents task submit "Long description here..." --title "Short title"

# ❌ Wrong (--description is not a valid flag, silently ignored)
tmux-agents task submit --description "Long description" --title "Short title"

6. Not Yet Implemented Commands

These commands are registered but will return errors:

• daemon run — use daemon start --foreground instead
• daemon logs — use tail -f ~/.tmux-agents/daemon.log instead
• agent output --follow — use agent attach for live monitoring instead

Quick Start Workflows

Spawn a single agent

# Basic spawn
tmux-agents agent spawn "Fix the login bug in auth.ts" --role coder --provider claude

# Spawn into a specific swim lane (inherits lane workdir, provider, toggles)
tmux-agents agent spawn "Fix the login bug" --role coder --lane backend

Submit and start a task

# With just description (short)
tmux-agents task submit "Refactor database layer" \
  --priority high --column todo --role coder \
  --lane backend --auto-start --auto-pilot

# With title + detailed description (recommended for complex tasks)
tmux-agents task submit "Bug: Database connection pool exhaustion under high load.
Need to investigate connection lifecycle, implement proper cleanup,
add connection timeout handling, and test with load simulation.

Acceptance criteria:
- No connection leaks under 1000 req/s
- Proper error handling on pool exhaustion
- Metrics for pool usage" \
  --title "Fix database connection pool leak" \
  --priority high --column todo --role coder \
  --lane backend --auto-start --auto-pilot

Fan-out a prompt to multiple agents

tmux-agents fan-out "Review this PR for security issues" --count 3 --provider claude

Create a coding team

tmux-agents team quick-code /path/to/project

Run a pipeline

tmux-agents pipeline create "deploy" --stages '[
  {"name":"lint","role":"coder","prompt":"Run linting"},
  {"name":"test","role":"tester","prompt":"Run tests","dependencies":["lint"]},
  {"name":"deploy","role":"ops","prompt":"Deploy to staging","dependencies":["test"]}
]'
tmux-agents pipeline run <pipeline-id>

Command Reference Overview

For complete command syntax and all flags, see references/commands.md.

Key Patterns

Task Lifecycle

submit (backlog/todo) -> start (doing, agent spawned) -> complete (done) -> close
                                                      -> stop (paused)
                                                      -> cancel (cancelled)

Agent Task Flow

1. Submit task with task submit or kanban submit
2. Start with task start <id> or kanban start <id> (spawns agent)
3. Monitor with task watch <id> or task output <id> --follow
4. Agent auto-moves task to done on completion (if --auto-close)

Progress Reporting & Heartbeats

Running tasks receive automatic heartbeat messages every 5 minutes asking the agent for a progress update. The agent responds with a structured progress marker that the daemon detects and stores in the task's output field.

• Live progress: Check task output <id> to see the latest progress (phase, status, files modified)
• Heartbeat-driven: The daemon pastes a heartbeat prompt into the agent's tmux pane; the agent responds with <task-progress> markers
• Auto-completion: When --auto-close is enabled, the agent signals done via <promise>DONE</promise> and the daemon completes the task and closes the tmux session
• Works with all tasks: Progress reporting is enabled for all started tasks, regardless of --auto-close

Swim Lane Isolation

Lanes scope work by directory, provider, and concurrency. Lanes can also set default toggles (--auto-start, --auto-pilot, --auto-close, --use-worktree, --use-memory) that are inherited by all tasks submitted to that lane:

# Basic lane
tmux-agents kanban create-lane frontend --workdir ./src/ui --provider claude --wip-limit 3

# Fully autonomous lane (all tasks auto-start, auto-pilot, auto-close)
tmux-agents kanban create-lane backend --workdir ./src/api --provider claude --wip-limit 2 \
  --auto-start --auto-pilot --auto-close

# Add context instructions (injected into every agent in the lane)
tmux-agents kanban edit-lane <lane-id> --context "Build after changes, then commit."

# Tasks inherit lane defaults — no need to pass --auto-start --auto-pilot per task
tmux-agents kanban submit "Add rate limiting" --lane backend --role coder

Runtime Selection

All runtimes wrap tmux with different exec prefixes:

# Local (default)
tmux-agents agent spawn "task" --role coder

# Remote SSH
tmux-agents runtime add prod-server --type ssh --host user@10.0.1.5
tmux-agents agent spawn "task" --role coder --runtime prod-server

# Docker
tmux-agents runtime add dev-container --type docker --image node:20
tmux-agents agent spawn "task" --role coder --runtime dev-container

# Kubernetes
tmux-agents runtime add k8s-cluster --type kubernetes --namespace agents
tmux-agents agent spawn "task" --role coder --runtime k8s-cluster

Output Formats

Most commands support --json for machine-readable output:

tmux-agents agent list --json | jq '.[] | select(.status == "working")'
tmux-agents task list --json
tmux-agents kanban board --json

Default output uses colored tables with status icons.

Monitoring

# Dashboard overview
tmux-agents dashboard

# Follow agent output in real-time
tmux-agents agent output <id> --follow

# Watch task progress
tmux-agents task watch <id> --output

# Daemon logs
tmux-agents daemon logs --follow

# Daemon statistics
tmux-agents daemon stats

Common Workflow Patterns

For multi-step workflow examples (team setup, pipeline orchestration, kanban-driven development), see references/workflows.md.

Transport

The CLI connects to the daemon via:

1. Unix socket ~/.tmux-agents/daemon.sock (preferred)
2. HTTP http://127.0.0.1:3456 (fallback)
3. WebSocket ws://127.0.0.1:3457 (events/streaming)

Connection is automatic — no configuration needed for local use.

Remote Daemon

Connect to a daemon running on another machine:

# CLI / TUI — use --ip flag
tmux-agents task list --ip 192.168.1.10:3456
tmux-agents tui --ip 192.168.1.10:3456

# Or via SSH tunnel (daemon stays on 127.0.0.1, more secure)
ssh -L 3456:127.0.0.1:3456 -L 3457:127.0.0.1:3457 user@remote -N &
tmux-agents tui --ip localhost:3456

VS Code: set tmuxAgents.daemonUrl to host:port in settings. HTTP port +1 = WS port (3456→3457).

Start daemon for remote access: tmux-agents daemon start --bind 0.0.0.0