Agent Teams

Overview

tmux-ide supports two related workflows:

Agent Teams for lead + teammate coordination inside Claude Code
Missions for milestone-gated execution with orchestration, validation, research, and metrics

If you are starting fresh on v2.0, use missions mode first. It keeps the agent-team layout, but adds the orchestrator, milestone gating, validation contracts, and monitoring on top.

Agent teams are experimental in Claude Code and disabled by default. tmux-ide automatically sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 when your config includes a team block.

Missions Mode

The most powerful way to use agent teams is missions mode. The orchestrator manages planning handoff, milestone order, specialty-aware dispatch, validation, and completion.

tmux-ide init --template missions
tmux-ide mission create "Ship auth v2" -d "JWT login, refresh, and validation coverage"
tmux-ide

The missions template creates a lead pane plus specialized teammates for frontend, backend, validation, and research. When the mission is active, the orchestrator drives work automatically.

Mission Lifecycle

Planning. The lead agent creates milestones, tasks, and the validation contract while the mission is in planning.
Execution. The orchestrator dispatches tasks in milestone order and prefers agents whose specialty matches the task.
Validation. When a milestone completes, the validator verifies the claimed assertions.
Completion. When all milestones are done and assertions pass, the mission is marked complete and the completion flow can create a PR.

For the full end-to-end lifecycle walkthrough, see Missions Workflow.

Quick Start

tmux-ide init --template missions
tmux-ide mission create "Build a todo API" -d "Plan, implement, validate, and summarize the result"
tmux-ide milestone create "Foundation" --sequence 1
tmux-ide milestone create "Implementation" --sequence 2
tmux-ide milestone create "Validation" --sequence 3
tmux-ide mission plan-complete
tmux-ide

Milestones

Milestones are sequential execution phases. In missions mode, M1 must complete before M2 can start.

tmux-ide milestone create "Foundation" --sequence 1
tmux-ide milestone create "Frontend" --sequence 2
tmux-ide milestone list
tmux-ide milestone show M1

New milestones start as active only when they are the first phase. Later ones begin as locked and are activated by the orchestrator after validation passes.

Skill-Based Dispatch

Tasks can declare a --specialty, and panes can advertise both a specialty and a skill.

panes:
  - title: Frontend Agent
    command: claude
    role: teammate
    specialty: frontend
    skill: frontend

The skill value loads .tmux-ide/skills/frontend.md into dispatch prompts. The specialty value is used by the orchestrator when selecting the best pane for a task.

tmux-ide task create "Build login page" --specialty frontend --milestone M1

That task is a better match for a pane whose specialty is frontend.

Validation Contracts

Validation contracts define what “done” means before work begins. Store them in .tasks/validation-contract.md with assertion IDs such as VAL-AUTH-001.

**VAL-AUTH-001**: Login endpoint returns JWT on valid credentials
**VAL-AUTH-002**: Invalid credentials return 401

Tasks can claim the assertions they fulfill:

tmux-ide task create “Implement login” --milestone M1 --fulfills “VAL-AUTH-001,VAL-AUTH-002”
tmux-ide validate coverage
tmux-ide validate assert VAL-AUTH-001 --status passing --evidence “API test passed”
tmux-ide validate report

Use validate coverage during planning to make sure every assertion is claimed before execution starts.

After all tasks in a milestone complete, the orchestrator auto-dispatches the validator agent to verify the milestone's assertions. The validator runs the checks defined in the contract, updates each assertion to passing, failing, or blocked, and reports the results. If any assertion fails, the orchestrator can trigger remediation tasks before advancing to the next milestone.

For the full contract format and assertion lifecycle, see Validation Contracts.

Knowledge Library

Missions share context through .tmux-ide/library/ and other repo-level prompt sources:

architecture.md is injected into every dispatch prompt
learnings.md is appended as tasks complete with --summary
research-findings.md accumulates completed research output
AGENTS.md defines project boundaries and operating rules for every agent

This keeps discoveries from one task available to the next dispatch without rebuilding context manually.

For details on library structure and how content flows between agents, see Knowledge Library.

Researcher Agent

The researcher provides continuous internal auditing. Research can trigger at mission start, milestone progress, milestone completion, retry clusters, or stalls.

panes:
  - title: Researcher
    command: claude
    role: researcher
    specialty: researcher
    skill: researcher

You can inspect or trigger research manually:

tmux-ide research status
tmux-ide research trigger periodic

Monitoring

Use the metrics CLI for high-level progress, per-agent utilization, and bottleneck analysis:

tmux-ide metrics
tmux-ide metrics agents
tmux-ide metrics timeline
tmux-ide metrics eval
tmux-ide metrics history

The Command Center runs on http://localhost:6060 by default, and the dashboard runs on http://localhost:6061.

Classic Agent Teams

Classic agent teams are still supported when you want a lead pane coordinating Claude teammates directly, without mission orchestration.

tmux-ide init --template agent-team
tmux-ide

This creates a layout with a lead and two teammate-ready Claude panes in the top row, plus a dev server and shell in the bottom row.

Configuration

Add a team block to your ide.yml and annotate Claude panes with roles:

name: my-app

team:
  name: my-app

rows:
  - size: 70%
    panes:
      - title: Lead
        command: claude
        role: lead
        focus: true
      - title: Frontend
        command: claude
        role: teammate
        task: "Work on React components and pages"
      - title: Backend
        command: claude
        role: teammate
        task: "Work on API routes and server logic"

  - panes:
      - title: Next.js
        command: pnpm dev
      - title: Shell

`team` fields

Field	Required	Description
`team.name`	Yes	Team name to reference in your Claude prompts
`team.model`	No	Optional metadata for your own team conventions
`team.permissions`	No	Optional metadata for your own team conventions

Pane role fields

Field	Description
`role`	Layout metadata for Claude panes. Supported values are `lead`, `teammate`, `planner`, `validator`, and `researcher`.
`task`	Suggested task description for a pane. Useful prompt scaffolding for classic team workflows.
`specialty`	Routing hint used by the orchestrator to match tasks to the best pane.
`skill`	Loads `.tmux-ide/skills/<name>.md` into prompts for that pane.

How Classic Teams Work

When you launch a team-enabled config, tmux-ide:

Creates the tmux session and panes
Sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Starts the configured Claude panes
Leaves you in a lead-focused workspace ready for team setup prompts

From there, ask Claude in the lead pane to organize the team, for example:

Start an agent team named my-app. Use the Frontend pane for React components and the Backend pane for API routes.

Claude Code handles the actual team creation, coordination, and task assignment.

Enable Teams on an Existing Config

tmux-ide config enable-team --name "my-team"
tmux-ide config set rows.0.panes.1.task "Work on frontend components"
tmux-ide config set rows.0.panes.2.task "Work on API routes"
tmux-ide validate --json

Disable Teams

tmux-ide config disable-team

This removes the team config and all role and task fields.

Team Lead Self-Configuration

The lead pane can reconfigure its own workspace from inside tmux-ide:

tmux-ide config add-pane --row 0 --title "Reviewer" --command "claude"
tmux-ide config set rows.0.panes.3.role teammate
tmux-ide config set rows.0.panes.3.task "Review code and check for issues"
tmux-ide validate --json
tmux-ide restart

Templates

Missions

tmux-ide init --template missions

┌───────────┬───────────┬───────────┐
│           │           │           │
│   Lead    │ Frontend  │  Backend  │  70%
│           │           │           │
├───────────┼───────────┼───────────┤
│ Validator │ Researcher│   Shell   │  30%
└───────────┴───────────┴───────────┘

Agent Team

tmux-ide init --template agent-team

┌───────────┬───────────┬───────────┐
│           │           │           │
│   Lead    │Teammate 1 │Teammate 2 │  70%
│           │           │           │
├───────────┴─────┬─────┴───────────┤
│   Dev Server    │     Shell       │  30%
└─────────────────┴─────────────────┘

Best Practices

Start with tmux-ide init --template missions for new multi-agent projects
Keep one lead and 2-4 specialized agents instead of a wide generic team
Add specialty and skill fields so dispatch prompts stay targeted
Define the validation contract before planning is complete
Run tmux-ide validate coverage before tmux-ide mission plan-complete
Use tmux-ide metrics eval to spot bottlenecks and retry-heavy agents
Use tmux-ide restart after changing the layout or pane roles