tmux-ide 2.0

tmux-ide 2.0 transforms from a terminal IDE into an autonomous multi-agent development platform. Define a mission, and agents self-organize through milestones, validation contracts, and skill-based dispatch.

New Features

Mission Lifecycle

Full autonomous mission pipeline: planning → active → validating → complete.

tmux-ide mission create "Build auth system" -d "JWT + refresh tokens"
tmux-ide                    # orchestrator dispatches planning to lead agent
tmux-ide mission status     # track progress

The orchestrator dispatches planning to the lead pane, which creates milestones, tasks, and a validation contract. When planning completes (tmux-ide mission plan-complete), the first milestone activates and task dispatch begins.

Milestones

Sequential execution phases with automatic gating. Tasks only dispatch when their milestone is active and all predecessor milestones are done.

tmux-ide milestone create "Foundation" --sequence 1
tmux-ide milestone create "Features" --sequence 2
tmux-ide milestone list

When all tasks in a milestone complete, it auto-progresses: triggers validation (if a contract exists), or marks done and activates the next milestone.

Validation Contracts

Assertion-based verification with independent validation. Create .tasks/validation-contract.md with testable assertions:

**VAL-AUTH-001**: Auth endpoint returns 200 with valid JWT
**VAL-AUTH-002**: Refresh token rotation works correctly
**VAL-DB-001**: User data persists across restarts

Tasks claim assertions via --fulfills:

tmux-ide task create "Implement JWT" --milestone M1 --fulfills "VAL-AUTH-001,VAL-AUTH-002"

When a milestone's tasks complete, a validator agent independently checks each assertion:

tmux-ide validate assert VAL-AUTH-001 --status passing --evidence "endpoint returns 200"
tmux-ide validate assert VAL-AUTH-002 --status failing --evidence "rotation broken"

Failed assertions auto-create remediation tasks. The milestone resets to active until all assertions pass.

Skill-Based Dispatch

Match task specialty to agent capabilities. Define skills in .tmux-ide/skills/:

# .tmux-ide/skills/frontend.md
---
name: frontend
specialties: [react, css, typescript]
role: teammate
description: Frontend component specialist
---
You are a frontend developer. Focus on React components.

Tasks with --specialty frontend dispatch to agents with matching specialties. Generalist agents (no specialties) handle unspecialized work. Tasks wait for the right specialist instead of dispatching to a wrong one.

tmux-ide skill list          # show available skills
tmux-ide skill create myskill # scaffold from template
tmux-ide skill validate       # check pane→skill references

Rich Dispatch Prompts

Agents receive layered context: mission narrative, milestone context, AGENTS.md boundaries, skill body, goal/acceptance criteria, task details with fulfills, recent completions from the same milestone, library references (architecture + tag-matched), and services registry.

Knowledge Library

Shared learnings at .tmux-ide/library/. When a task completes with --summary, the text auto-appends to learnings.md. Architecture docs and tag-matched files are injected into dispatch prompts.

Researcher Agent

Continuous internal auditing triggered by: mission start, milestone progress thresholds, milestone completion, periodic intervals, retry clusters, stall detection, and discovered issues.

orchestrator:
  research:
    enabled: true
    triggers:
      mission_start: true
      milestone_progress: 3
      retry_cluster: true

Metrics and Monitoring

Session, task, agent, and mission telemetry:

tmux-ide metrics           # session summary
tmux-ide metrics agents    # per-agent utilization
tmux-ide metrics eval      # bottleneck milestones, high-retry agents
tmux-ide metrics history   # cross-mission comparison

Web Dashboard

Live dashboard at localhost:6060 with:

• KPI cards (completion rate, utilization, retry rate)
• Milestone timeline with progress bars
• Agent performance table
• Validation assertion status
• Activity timeline

Coverage Invariant

Every assertion in the validation contract must be claimed by at least one task's --fulfills. Warnings on dispatch and plan-complete if gaps exist.

tmux-ide validate coverage   # check assertion coverage

Services Registry

Centralize dev commands and ports in ide.yml:

orchestrator:
  services:
    dev: { command: "pnpm dev", port: 3000 }
    test: { command: "pnpm test" }
    db: { command: "docker compose up db", port: 5432, healthcheck: "pg_isready" }

Services are injected into dispatch prompts so agents know how to run/check services.

Multi-Agent Support

Detect Claude Code, Codex (including platform-suffixed binaries like codex-aarch64-a), and any CLI agent via command prefix matching and version string detection.

Breaking Changes

• Git worktree isolation removed -- agents now work in the project directory. worktree_root and cleanup_on_done config options removed.
• task.branch field removed -- tasks no longer track individual branches.
• Default command center port changed to 6060.

Bug Fixes

• Unified slugify function (consistent 40-char limit across task store and orchestrator)
• Goal prompt newlines preserved (removed erroneous .replace(/\n+/g, " "))
• Theme customization applied correctly in widget createTheme()
• Config mutation validation (re-validates with Zod after mutation)
• Dependency cycle detection in task creation
• PR creation failures surfaced in JSON output

New CLI Commands

# Mission lifecycle
tmux-ide mission create "title" [-d "desc"]
tmux-ide mission plan-complete
tmux-ide mission status [--json]

# Milestones
tmux-ide milestone create "title" --sequence N
tmux-ide milestone list [--json]
tmux-ide milestone show <id> [--json]
tmux-ide milestone update <id> --status active|done|locked

# Validation
tmux-ide validate show [--json]
tmux-ide validate assert <ID> --status passing|failing|blocked
tmux-ide validate report [--json]
tmux-ide validate coverage [--json]

# Skills
tmux-ide skill list [--json]
tmux-ide skill show <name> [--json]
tmux-ide skill create <name>
tmux-ide skill validate

# Research
tmux-ide research status [--json]
tmux-ide research trigger <type>

# Metrics
tmux-ide metrics [--json]
tmux-ide metrics agents [--json]
tmux-ide metrics eval [--json]
tmux-ide metrics history [--json]

Migration from v1.x

1. Remove worktree config: Delete worktree_root and cleanup_on_done from ide.yml orchestrator section.
2. Update dispatch mode: Change dispatch_mode: tasks to dispatch_mode: missions to use the full mission lifecycle.
3. Add skills: Run tmux-ide init --template missions in a new directory to see the full setup, then copy .tmux-ide/skills/ to your project.
4. Task branch references: Any code referencing task.branch should use task.milestone instead.