# Configuration

> Reference for the optional .tmux-ide/workspace.yml layout file and the global ~/.tmux-ide/config.json settings file, with every field and default.

tmux-ide reads two files, both optional:

| File                      | Scope       | Purpose                                                    |
| ------------------------- | ----------- | ---------------------------------------------------------- |
| `.tmux-ide/workspace.yml` | One project | A repeatable tmux layout: panes, commands, directories     |
| `~/.tmux-ide/config.json` | Your user   | App, theme, notification, restore and tmux chrome settings |

## 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:

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

Or [start from a template](/docs/templates).

### Example layout

```yaml
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](/docs/commands#open-tmux-ide).

### Fields

#### Top level

| Field       | Required | Notes                                                  |
| ----------- | -------- | ------------------------------------------------------ |
| `version`   | yes      | Must be `1`                                            |
| `name`      | no       | tmux session name; falls back to the project directory |
| `before`    | no       | Pre-launch shell hook                                  |
| `terminal`  | no       | Repeatable tmux rows, panes, and per-session colors    |
| `app`       | no       | App views; validated, not read by the 2.9 app          |
| `harnesses` | no       | Agent command profiles; validated, not run yet         |
| `agents`    | no       | Agent role profiles; validated, not run yet            |
| `missions`  | no       | Mission defaults; validated, not run yet               |

#### Rows

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

#### Panes

| Field     | Type    | Notes                                         |
| --------- | ------- | --------------------------------------------- |
| `id`      | string  | Stable semantic pane ID; unique when provided |
| `title`   | string  | Pane border label                             |
| `command` | string  | Command to run in the pane                    |
| `size`    | percent | Pane width such as `50%`                      |
| `dir`     | string  | Per-pane working directory                    |
| `focus`   | boolean | Initial focus                                 |
| `env`     | map     | String or numeric environment values          |
| `type`    | string  | Render a supported widget instead of a shell  |
| `target`  | string  | Target path for widgets that accept one       |

#### 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:

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

| Type       | Shows                                       |
| ---------- | ------------------------------------------- |
| `explorer` | A file tree (optionally rooted at `target`) |
| `changes`  | Git changes in the project                  |
| `preview`  | A preview of the explorer's selection       |
| `config`   | The workspace config editor                 |
| `sidebar`  | A fleet navigation column                   |

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](/docs/the-dock#panels) 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:

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

For the app's appearance, see [Appearance](/docs/theming).

### Editing the workspace from the CLI

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

```bash
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](/docs/commands) for the full `config` surface, and
[Templates](/docs/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.

```json
{
  "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`

| Field         | Default    | Effect                                                                                                        |
| ------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| `frontDoor`   | `true`     | Bare `tmux-ide` (no workspace file here) opens the app                                                        |
| `detachable`  | `false`    | Run `tmux-ide app` hosted in tmux so it survives the terminal; `Ctrl+Q` detaches (same as `--detachable`)     |
| `dragSelect`  | `"agents"` | When a left drag selects text locally instead of going to a mouse-enabled pane: `agents`, `always` or `never` |
| `newAgentCwd` | `"pane"`   | Where **New agent…** starts from Terminals: the focused pane's directory, or `"session"`                 |
| `kittyKeys`   | `true`     | Ask the host terminal for the kitty keyboard protocol; turn off if your terminal misbehaves                   |

### `theme`

| Field                                       | Default      | Effect                                                            |
| ------------------------------------------- | ------------ | ----------------------------------------------------------------- |
| `mode`                                      | `"system"`   | `system` (follow the terminal), `dark` or `light`                 |
| `preset`                                    | —            | A [theme preset](/docs/theming#theme-presets) id, such as `tokyo` |
| `automaticContrast`                         | `true`       | Correct low-contrast text across the app and terminal panes       |
| `accent`, `muted`, `fg`, `status`, `glyphs` | tmux colours | Colors and glyphs for the [tmux chrome](/docs/the-dock)           |

### `notifications`

| Field          | Default     | Effect                                                                         |
| -------------- | ----------- | ------------------------------------------------------------------------------ |
| `toast`        | `true`      | In-tmux toast when an agent becomes blocked or done                            |
| `macos`        | `false`     | Native macOS notification                                                      |
| `terminal`     | `true`      | Terminal-native banner (OSC 9 / OSC 99) for terminals that support it          |
| `delaySeconds` | `2`         | Wait before OS-level channels fire, and skip them if the state already changed |
| `sound`        | `"blocked"` | Play a sound on `blocked` only, on `all` notifications, or `none`              |

See [Notifications and events](/docs/notifications-events).

### Other sections

| Section        | Fields (defaults)                                                                                                                            | Effect                                                                                                      |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `restore`      | `resumeAgents` (`false`)                                                                                                                     | Make [`tmux-ide restore`](/docs/restore-resume) resume agent conversations by default                       |
| `updater`      | `tickMs` (`2000`), `snapshotEvery` (`15`)                                                                                                    | Background updater cadence and how often it writes restore snapshots                                        |
| `updates`      | `check` (`true`), `manifests` (`false`)                                                                                                      | Daily update check; also refresh the agent-detection manifest pack                                          |
| `worktrees`    | `dir` (`""`)                                                                                                                                 | Base directory for [`tmux-ide worktree`](/docs/worktrees); empty means `<repo>-worktrees`                   |
| `welcome`      | `show` (`true`)                                                                                                                              | Allow the one-time tmux chrome welcome card                                                                 |
| `integrations` | `offer` (`true`)                                                                                                                             | Allow the one-time offer to install the Claude Code integration                                             |
| `keys`         | `home` `M-h`, `popup` `M-p`, `cheatsheet` `M-k`, `menu` `M-m`, `sidebar` `M-b`, `panels` (`explorer` `M-e`, `changes` `M-g`, `config` `M-,`) | Key binds for the [tmux chrome](/docs/the-dock#the-keys); each also gets a prefix twin. Not used by the app |

## 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?

```bash
tmux-ide validate --json
```

Run it after every change to the file.

## See also

* [Workspace templates](/docs/templates) — ready-made layouts to start from
* [Appearance and themes](/docs/theming) — the app's theme settings
* [CLI reference](/docs/commands#inspect-and-edit-a-workspace) — `config`, `validate` and `init`