Workspace Layouts

Overview

.tmux-ide/workspace.yml is optional. The OpenTUI discovers 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

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

The launch resolver currently implements explorer, changes, preview, config, and sidebar. The setup wizard is a CLI surface (tmux-ide setup), not a workspace pane type. Explorer, changes, and config are also available as floating panels (prefix e / g / v, or ⌥e / ⌥g / ⌥,) from an adopted session — see Home, sidebar & panels.

App views

app.views controls the ordered views shown by the unified app. A simple view selects one of home, terminals, files, diff, or missions:

app:
  views:
    - id: home
      title: Home
      panel: home
    - id: terminals
      title: Terminals
      panel: terminals

Composite views use a recursive layout of panel, split, and tabs nodes. Node IDs must be unique within the view. Splits contain two to four children; tabs contain one to eight. When supplied, split weights must have one entry per child and a tab's active value must name one of its children.

Agent profiles and mission defaults

Harness commands may be a shell string or an executable/argv array. Agent roles are manager, implementer, reviewer, researcher, or validator:

harnesses:
  claude:
    adapter: claude
    command: [claude, --dangerously-skip-permissions]

agents:
  lead:
    harness: claude
    role: manager
  reviewer:
    harness: claude
    model: sonnet
    role: reviewer

missions:
  manager: lead
  reviewer: reviewer
  isolation: worktree
  max_concurrent_tasks: 3

Agent and mission references are validated. In the current release these blocks are declarative defaults only: the app can show its Missions panel, but the CLI does not yet launch or dispatch a mission from this workspace data.

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.9:

• app.frontDoor controls the default entry point. Bare tmux-ide launches the unified visual app by default (true); set it to false only when you deliberately need the retained classic entry path.

• 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.

• 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.

Editing config programmatically

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.

Use the typed harnesses, agents, and missions fields above for declarative profiles. Do not copy the legacy orchestrator runtime block into .tmux-ide/workspace.yml.