Getting Started

Prerequisites

• tmux — 3.2+ recommended (doctor requires ≥ 3.0; 3.6 is the smoothest)
• Node.js — ≥ 20
• Bun — only needed for the TUI surfaces (home cockpit, sidebar, floating panels)

The Homebrew install resolves tmux and Node.js for you — with it, there are no prerequisites to install by hand.

Check everything at once:

tmux-ide doctor

Install

Homebrew (macOS and Linux)

One command — tmux and Node.js are resolved as dependencies, nothing to install first:

brew install wavyrai/tap/tmux-ide

Homebrew skips npm lifecycle scripts, so wire the Claude Code pieces once after installing (the npm path below does this automatically):

tmux-ide integration install claude   # Claude Code hooks + skill sync

npm

npm i -g tmux-ide

Global install also registers the bundled Claude Code skill and enables CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in ~/.claude/settings.json if Claude Code is installed locally.

Adopt a session you already have

The fastest way to see tmux-ide is to point it at a tmux session you're already running. adopt adds a native chrome row — fleet tabs, live agent glyphs, and [ ⌂ home ] [ ⧉ switch ] [ ? keys ] triggers — and changes nothing else.

tmux-ide adopt work        # adopt the session named "work"
tmux-ide adopt --all       # adopt every live (non-internal) session

It's zero-risk by construction: adopt only sets tmux options. To reverse it:

tmux-ide unadopt work

If tmux-ide ever crashes or is uninstalled, your sessions keep running as plain tmux — the chrome is decoration, not a dependency. And because the chrome lives server-side, it renders from any client, including over SSH.

Turn on ground-truth agent status

By default tmux-ide infers agent state from the process tree and screen contents. For authoritative status, hook Claude Code's lifecycle so working/blocked/done come straight from the agent:

tmux-ide integration install claude

This writes a small POSIX hook script and registers it in ~/.claude/settings.json (a one-time backup is written next to it, and uninstall removes exactly the tmux-ide entries). It takes effect for new Claude Code sessions. See Agent detection for the two detection layers and the self-report contract any agent can use.

Start anywhere with the app

tmux-ide app opens the unified app — a full-screen IDE over your fleet. It works from any folder with no tmux server running, a genuine cold start:

tmux-ide app          # from any directory

A first-run welcome greets you, and Open folder… is a real filesystem picker: choose a directory and the app opens it as a terminal workspace, optionally remembering it as a project. Recently opened folders stay one click away.

If you'd like bare tmux-ide to open the app instead of the home cockpit, set the optional front-door flag in ~/.tmux-ide/config.json:

{ "app": { "frontDoor": true } }

It's opt-in — project config auto-launch and tmux-ide team are unaffected. See Home, sidebar & panels and What's new in 2.7.

Optional: describe a layout with workspace.yml

Adopt works on sessions you launch however you like. If you'd rather have tmux-ide build the layout, scaffold .tmux-ide/workspace.yml:

tmux-ide init          # auto-detects your stack and writes .tmux-ide/workspace.yml
tmux-ide               # launch the session from workspace.yml

A minimal config:

version: 1
name: my-app

terminal:
  rows:
    - size: 70%
      panes:
        - title: Claude
          command: claude
          focus: true
        - title: Shell
    - panes:
        - title: Dev Server
          command: pnpm dev

Sessions launched from .tmux-ide/workspace.yml are adopted automatically. Legacy ide.yml files remain compatible; use tmux-ide migrate --dry-run to preview conversion. See Configuration for the full format.

Where to go next

• The dock & keys — the status bar and every keystroke
• Notifications & events — the who-needs-me loop
• Restore & resume — survive a tmux server death
• Worktrees — parallel agents on parallel branches
• CLI reference — every command