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.

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.

File locations

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

Global: ~/.config/monocle/config.json (or $XDG_CONFIG_HOME/monocle/config.json)
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

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

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

Get Started

Core Concepts

Guides

Configuration

Reference

File locations

Example config

Settings

​File locations

​Example config

​Settings

File locations

Example config

Settings