Skip to main content
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:
  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

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

SettingValuesDefaultDescription
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.
wraptrue, falsefalseWord-wrap long lines in diffs
tab_sizeinteger4Spaces per tab character
context_linesinteger3Unchanged lines shown around diff hunks
ignore_patternsstring array[]Glob patterns for files to exclude
min_diff_widthinteger80Minimum character width for the diff viewer in side-by-side layout
mousetrue, falsetrueEnable mouse interactions (click, scroll, drag)
auto_focus_modetrue, falsefalseAuto-enter focus mode (hide sidebar, enable wrap) when reviewing plans
comment_expandtrue, falsetrueAuto-expand comments when the cursor hovers over them
comment_expand_delayinteger (ms)2000Delay in milliseconds before a comment auto-expands on hover
review_trackingtrue, falsetrueEnable 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_timeoutduration 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.
keybindingsobject{}Custom key overrides (see Keybindings)
review_format.include_snippetstrue, falsetrueInclude code snippets in formatted reviews
review_format.max_snippet_linesinteger10Truncate snippets longer than this
review_format.include_summarytrue, falsetrueInclude 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.