Configuration

tmux-ide reads two files, both optional:

Workspace file

.tmux-ide/workspace.yml is optional. The app and tmux-ide adopt work with ordinary tmux sessions without it. Use a workspace file when you want tmux-ide to build a repeatable layout with named panes, commands, working directories, and environment variables.

Legacy ide.yml files are still supported through a compatibility adapter. Preview migration with tmux-ide migrate --dry-run; write the new file with tmux-ide migrate --write.

Scaffold one from your detected stack:

tmux-ide init          # or: tmux-ide detect --write

Or start from a template.

Example layout

version: 1
name: my-app # tmux session name
before: pnpm install # runs before the layout launches

terminal:
  rows:
    - size: 70% # row height
      panes:
        - { title: Claude, command: claude, focus: true, size: 50% }
        - { title: Shell }
    - panes:
        - { title: Changes, type: changes }
        - { title: Dev, command: pnpm dev, dir: apps/web, env: { PORT: "3000" } }

Launch it with tmux-ide or tmux-ide start in the project directory; see Open tmux-ide.

Fields

Top level

Rows

terminal:
  rows:
    - size: 70% # optional row height (percent); rows split evenly if omitted
      panes: [...] # at least one pane

Panes

Widget panes

Set type to run a built-in widget program in a pane instead of a shell. The widget is an ordinary process inside the tmux pane, so it shows up in Terminals like any other program:

panes:
  - title: Explorer
    type: explorer
    target: src/
  - title: Changes
    type: changes

The setup wizard is a CLI surface (tmux-ide setup), not a workspace pane type. Explorer, changes and config also open as floating panels in tmux chrome sessions.

App views

app.views is accepted for forward compatibility. The schema lists the panel kinds home, terminals, files, diff and missions, with panel, split and tabs layout nodes. The 2.9 app does not read app.views: it always shows Home and Terminals, and the files, diff and missions views are not part of this release. Validation still checks the block, so an existing file keeps working.

Agent profiles and mission defaults

The harnesses, agents and missions blocks are validated, so existing files keep working, but nothing in 2.9.3 launches or dispatches them. Start agents with Commands → New agent… in the app or with a pane command.

Per-session theme

The terminal.theme block sets tmux colors for this session's panes:

terminal:
  theme:
    accent: colour75
    border: colour238
    bg: colour235
    fg: colour248

For the app's appearance, see Appearance.

Editing the workspace from the CLI

Use the typed config subcommands to mutate workspace fields, then validate the result with structured output:

tmux-ide config set name "my-app"
tmux-ide config add-pane --row 0 --title "Claude" --command "claude"
tmux-ide validate --json

See the CLI reference for the full config surface, and Templates for ready-made starting points.

Legacy compatibility

The legacy team, pane role/task metadata, sidebar, and orchestrator blocks are not represented in WorkspaceConfigV1. The migration command reports those fields as diagnostics instead of silently dropping them.

Do not copy the legacy orchestrator runtime block into .tmux-ide/workspace.yml; nothing in 2.9.3 runs agent or mission profiles.

Global config

~/.tmux-ide/config.json holds user-wide settings. Set TMUX_IDE_CONFIG to use another path. Every field is optional: a missing or mistyped value falls back to its default, and a malformed file never stops tmux-ide from starting. The app writes changes made in Appearance… back to this file.

{
  "theme": { "mode": "system", "preset": "tokyo", "automaticContrast": true },
  "notifications": {
    "toast": true,
    "macos": false,
    "terminal": true,
    "delaySeconds": 2,
    "sound": "blocked"
  },
  "restore": { "resumeAgents": false },
  "app": { "detachable": false }
}

app

theme

notifications

See Notifications and events.

Other sections

Common questions

Do I need a workspace file?

No. The app discovers ordinary tmux sessions, and tmux-ide adopt works on any session. A workspace file only matters when you want tmux-ide to build a repeatable layout.

Where does the session name come from?

From name in .tmux-ide/workspace.yml, or the project directory's name when name is not set.

How do I check my file?

tmux-ide validate --json

Run it after every change to the file.

See also

• Workspace templates — ready-made layouts to start from
• Appearance and themes — the app's theme settings
• CLI reference — config, validate and init