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

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 "set up agent teams" 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:

The install script (both curl | sh and npm install -g) copies SKILL.md into ~/.claude/skills/tmux-ide/. Claude Code picks this up automatically — no extra configuration needed.

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/

Once installed, just ask Claude Code something like:

"Set up a tmux IDE for this project"

and it will handle the rest.