tmux-ide

Turn any project into a tmux-powered terminal IDE with a simple ide.yml config file.

Install

npm install -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 on the machine.

Quick Start

tmux-ide init         # Scaffold ide.yml (auto-detects your stack)
tmux-ide              # Launch the IDE
tmux-ide stop         # Kill the session
tmux-ide restart      # Stop and relaunch
tmux-ide attach       # Reattach to a running session
tmux-ide inspect      # Inspect effective config + runtime state

ide.yml Format

name: project-name # tmux session name

before: pnpm install # optional pre-launch hook

rows:
  - size: 70% # row height percentage
    panes:
      - title: Editor # pane border label
        command: vim # command to run (optional)
        size: 60% # pane width percentage (optional)
        dir: apps/web # per-pane working directory (optional)
        focus: true # initial focus (optional)
        env: # environment variables (optional)
          PORT: 3000
      - title: Shell

  - panes:
      - title: Dev Server
        command: pnpm dev
      - title: Tests
        command: pnpm test

theme: # optional color overrides
  accent: colour75
  border: colour238
  bg: colour235
  fg: colour248

Commands

| Command | Description | | -------------------------------------------------- | --------------------------------------- | | tmux-ide | Launch IDE from ide.yml | | tmux-ide <path> | Launch from a specific directory | | tmux-ide init [--template <name>] | Scaffold a new ide.yml | | tmux-ide stop | Kill the current IDE session | | tmux-ide restart | Stop and relaunch the IDE session | | tmux-ide attach | Reattach to a running session | | tmux-ide ls | List all tmux sessions | | tmux-ide status | Show session status | | tmux-ide inspect | Show effective config and runtime state | | tmux-ide doctor | Check system requirements | | tmux-ide validate | Validate ide.yml | | tmux-ide detect | Detect project stack and explain why | | tmux-ide detect --write | Detect and write ide.yml | | tmux-ide config | Dump config as JSON | | tmux-ide config set <path> <value> | Set a config value | | tmux-ide config add-pane --row <N> | Add a pane to a row | | tmux-ide config remove-pane --row <N> --pane <M> | Remove a pane | | tmux-ide config add-row [--size <percent>] | Add a new row | | tmux-ide config enable-team --name <name> | Enable agent teams | | tmux-ide config disable-team | Disable agent teams |

All commands support --json for structured output.

tmux-ide detect now includes reasoning about the package manager, language, framework, and dev-command signals it used. tmux-ide inspect combines config validation, resolved layout details, and live tmux state in one command.

Templates

Use tmux-ide init --template <name> with one of:

• default - General-purpose layout
• nextjs - Next.js development
• convex - Convex + Next.js
• vite - Vite project
• python - Python development
• go - Go development
• agent-team - Agent team with lead + teammates
• agent-team-nextjs - Agent team for Next.js
• agent-team-monorepo - Agent team for monorepos

Contributor Workflow

The repo now uses a pnpm workspace with a root CLI package and a separate docs app package:

pnpm install
pnpm test
pnpm docs:build
pnpm check
pnpm pack:check

pnpm check is the intended local pre-push command and matches the default release checklist. npm publish is still guarded by prepublishOnly, so publishing runs the same full check path automatically.

CI

GitHub Actions validates:

• the Node CLI test suite on Node 18, 20, and 22
• the docs site production build
• the package can be packed successfully with npm pack --dry-run

That keeps the release surface small but catches the main regressions for a CLI-first package.

Open Source Project Files

• CONTRIBUTING.md for local setup and contribution workflow
• RELEASE.md for the publish checklist
• CHANGELOG.md for release notes
• SECURITY.md for vulnerability reporting

Release note convention:

• Keep the next version under an Unreleased heading in CHANGELOG.md until the tag is cut.
• Move it to a dated release entry when the release is actually published.

Requirements

• tmux >= 3.0
• Node.js >= 18

License

MIT