Workspace Layouts

Overview

.tmux-ide/workspace.yml is optional. tmux-ide adopt works on any session you launch however you like — but if you want tmux-ide to build the layout, describe it in .tmux-ide/workspace.yml and run tmux-ide. Sessions launched from a config are adopted automatically, so the dock and agent detection are on from the start.

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

Minimal example

version: 1
name: my-app # tmux session name

terminal:
  rows:
    - size: 70% # row height
      panes:
        - title: Claude
          command: claude
          focus: true
        - title: Shell
    - panes:
        - title: Dev Server
          command: pnpm dev
        - title: Tests
          command: pnpm test

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 render a built-in TUI widget in a pane instead of a shell:

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

Available types are explorer, changes, preview, setup, config, and sidebar. The same widgets are available as floating panels (prefix e / g / v, or ⌥e / ⌥g / ⌥,) from any adopted session — see Home, sidebar & panels.

Per-session theme

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

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

For the product-wide palette that colors the dock, chips, panels, and widgets, use ~/.tmux-ide/config.json instead — see Theming & config.

The global config & in-app settings

.tmux-ide/workspace.yml describes one project's layout. Product-wide behavior lives in ~/.tmux-ide/config.json (override the path with TMUX_IDE_CONFIG) — the same file that holds the shared theme. Two things worth knowing for 2.7:

• app.frontDoor flips the default entry point: with { "app": { "frontDoor": true } }, bare tmux-ide launches the unified app (tmux-ide app) instead of the home cockpit. Default false; project config auto-launch and tmux-ide team are unaffected.

• app.detachable makes plain tmux-ide app run hosted: the app lives in a tmux session of its own and your terminal attaches to it, so the cockpit survives the terminal and reattaches from anywhere (^q detaches instead of quitting). Default false — same as passing --detachable every time. See the app surfaces.

• Settings are editable in the app. Inside tmux-ide app, press F5 and type "settings" for a palette command per setting — no JSON required. Edits write back to ~/.tmux-ide/config.json atomically:

  Setting	Config field
  Accent color	theme.accent
  Notifications	notifications (channels & transitions)
  Quiet hours	notifications.quietHours
  Update cadence	updater, updates
  Crash restore	restore

  Keyboard shortcuts have a read-only viewer, and a guarded "reset to defaults" removes your overrides so the built-in defaults take over.

See Theming & config for the full palette, and What's new in 2.7.

Editing config programmatically

Every field is reachable from the CLI with --json output, e.g.:

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.

Agent teams & orchestration

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.

Mission runtime wiring is future work for the workspace config model. Do not add mission or orchestrator runtime fields to .tmux-ide/workspace.yml yet.