Getting Started

Prerequisites

• tmux installed (brew install tmux on macOS)
• Node.js 18+

Install

npm i -g tmux-ide

Or use it directly with npx — no install needed:

npx tmux-ide

Create your first workspace

Navigate to your project and scaffold a config:

cd ~/Developer/my-project
tmux-ide init

This creates an ide.yml in your project root:

name: my-project

rows:
  - size: 70%
    panes:
      - title: Claude 1
        command: claude
      - title: Claude 2
        command: claude

  - panes:
      - title: Dev Server
      - title: Shell

Launch

tmux-ide

That's it. You'll get a tmux session with labeled panes, split exactly as configured.

Stop

Detach with Ctrl-b d to leave it running in the background, or kill it:

tmux-ide stop

Restart

If you've changed your ide.yml, restart to apply the new layout:

tmux-ide restart

Reconnect

If you detach or close your terminal, just run tmux-ide again — it will reattach to the existing session:

tmux-ide

Or use tmux directly:

tmux attach -t my-project

Missions Mode (Autonomous)

For fully autonomous multi-agent orchestration, use missions mode:

tmux-ide init --template missions
tmux-ide mission create "Build auth system" -d "JWT + refresh tokens"
tmux-ide

What tmux-ide init --template missions scaffolds

.tmux-ide/skills/    — agent role definitions
.tmux-ide/library/   — architecture.md, learnings.md stubs
.tasks/              — validation-contract.md stub
AGENTS.md            — project boundaries
ide.yml              — session config with orchestrator

This gives you:

• 6 agent panes (lead, frontend, backend, validator, researcher, shell)
• Web dashboard at http://localhost:6060
• Fully autonomous orchestration — the lead plans, agents execute, validators verify

The orchestrator dispatches planning to the lead pane, which creates milestones, tasks, and a validation contract. Once planning completes (tmux-ide mission plan-complete), the orchestrator manages everything: skill-matched dispatch, milestone gating, validation, remediation, and mission completion.

Monitor progress:

tmux-ide mission status       # milestone + task + validation progress
tmux-ide metrics              # session duration, agent utilization, completion rates
tmux-ide validate coverage    # check assertion coverage

See Configuration for all orchestrator options and What's New in 2.0 for the full feature list.

Missions Mode Quick Start

For the full mission lifecycle walkthrough, see Missions Workflow. That guide covers planning, execution, validation, and completion end-to-end. For details on validation contracts and the knowledge library, see Validation Contracts and Knowledge Library.

Claude Code Skill

tmux-ide ships with a built-in Claude Code skill. When you install tmux-ide, the skill is automatically registered so Claude Code knows how to configure and manage your workspace.

What the skill enables:

• Ask Claude to "set up a tmux IDE" and it will auto-detect your stack, present layout options with ASCII diagrams, and write the config for you
• Ask Claude to "add a pane" or "prepare an agent-team layout" and it will use the programmatic CLI to modify your ide.yml
• The team lead agent can self-configure — spawning new teammates, assigning tasks, and restarting the layout

How it works:

If Claude Code is already set up on the machine, the global install hook copies SKILL.md into ~/.claude/skills/tmux-ide/ and sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in ~/.claude/settings.json. That keeps the npm install side effects limited to existing Claude Code setups.

If you installed via npx (without a global install), you can manually register the skill:

mkdir -p ~/.claude/skills/tmux-ide
cp "$(npm root -g)/tmux-ide/skill/SKILL.md" ~/.claude/skills/tmux-ide/

If Claude Code is not installed yet, create ~/.claude/ first or complete Claude Code setup before using the automatic registration path.

And if you want agent teams enabled for Claude Code outside tmux-ide-launched sessions, add this to ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Once installed, just ask Claude Code something like:

"Set up a tmux IDE for this project"

and it will handle the rest.