> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmonocle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Config File

> Customize monocle's layout, diff style, and behavior with a JSON config file.

Monocle loads settings from JSON config files at startup. You can maintain a global config for personal preferences and a project config for repository-specific settings.

<Note>
  Config is read once when the background engine (`monocle serve`) starts, not
  each time the TUI launches. Because the engine is long-lived and shared across
  TUI sessions, editing a config file and relaunching `monocle` alone will not
  pick up the change. To apply config changes, run `monocle stop` and then start
  `monocle` again — this restarts the engine and reloads the config.
</Note>

## File locations

Monocle loads config files in this order, with the project config taking precedence over the global one:

1. **Global:** `~/.config/monocle/config.json` (or `$XDG_CONFIG_HOME/monocle/config.json`)
2. **Project:** `.monocle/config.json` in your working directory

Create either or both files — you only need to include the settings you want to override.

## Example config

```json theme={"dark"}
{
  "layout": "auto",
  "diff_style": "unified",
  "sidebar_style": "flat",
  "theme": "dark",
  "wrap": false,
  "tab_size": 4,
  "context_lines": 3,
  "ignore_patterns": [],
  "keybindings": {},
  "mouse": true,
  "min_diff_width": 80,
  "auto_focus_mode": false,
  "comment_expand": true,
  "comment_expand_delay": 2000,
  "review_tracking": true,
  "mark_reviewed_on_submit": "all",
  "idle_timeout": "30m",
  "review_format": {
    "include_snippets": true,
    "max_snippet_lines": 10,
    "include_summary": true
  }
}
```

## Settings

| Setting                           | Values                                  | Default     | Description                                                                                                                                                                           |
| --------------------------------- | --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `layout`                          | `"auto"`, `"side-by-side"`, `"stacked"` | `"auto"`    | Pane arrangement (`auto` switches based on terminal width)                                                                                                                            |
| `diff_style`                      | `"unified"`, `"split"`, `"file"`        | `"unified"` | Diff display mode (`file` shows raw content)                                                                                                                                          |
| `sidebar_style`                   | `"flat"`, `"tree"`                      | `"flat"`    | File list display mode                                                                                                                                                                |
| `theme`                           | `"dark"`, `"light"`                     | `"dark"`    | Color scheme for the TUI. Use `"light"` if your terminal has a light background.                                                                                                      |
| `wrap`                            | `true`, `false`                         | `false`     | Word-wrap long lines in diffs                                                                                                                                                         |
| `tab_size`                        | integer                                 | `4`         | Spaces per tab character                                                                                                                                                              |
| `context_lines`                   | integer                                 | `3`         | Unchanged lines shown around diff hunks                                                                                                                                               |
| `ignore_patterns`                 | string array                            | `[]`        | Glob patterns for files to exclude                                                                                                                                                    |
| `min_diff_width`                  | integer                                 | `80`        | Minimum character width for the diff viewer in side-by-side layout                                                                                                                    |
| `mouse`                           | `true`, `false`                         | `true`      | Enable mouse interactions (click, scroll, drag)                                                                                                                                       |
| `auto_focus_mode`                 | `true`, `false`                         | `false`     | Auto-enter focus mode (hide sidebar, enable wrap) when reviewing plans                                                                                                                |
| `comment_expand`                  | `true`, `false`                         | `true`      | Auto-expand comments when the cursor hovers over them                                                                                                                                 |
| `comment_expand_delay`            | integer (ms)                            | `2000`      | Delay in milliseconds before a comment auto-expands on hover                                                                                                                          |
| `review_tracking`                 | `true`, `false`                         | `true`      | Enable review state tracking, snapshots, and change detection between rounds. Set to `false` for raw diffs with no reviewed indicators.                                               |
| `mark_reviewed_on_submit`         | `"all"`, `"commented"`, `"manual"`      | `"all"`     | Which files to mark as reviewed when submitting (requires `review_tracking`, see [Review State](/concepts/review-state))                                                              |
| `idle_timeout`                    | duration string (e.g. `"30m"`, `"1h"`)  | `"30m"`     | How long `monocle serve` stays alive after the last client disconnects (plus a 60s grace window). Overridden by the `--idle-timeout` flag. Use `"0s"` or a negative value to disable. |
| `keybindings`                     | object                                  | `{}`        | Custom key overrides (see [Keybindings](/configuration/keybindings))                                                                                                                  |
| `review_format.include_snippets`  | `true`, `false`                         | `true`      | Include code snippets in formatted reviews                                                                                                                                            |
| `review_format.max_snippet_lines` | integer                                 | `10`        | Truncate snippets longer than this                                                                                                                                                    |
| `review_format.include_summary`   | `true`, `false`                         | `true`      | Include comment count summary in formatted reviews                                                                                                                                    |

<Note>
  Toggle keybindings (`T`, `t`, `w`, `f`) change settings for the current session only. Edit the config file to persist your preferences.
</Note>