Skip to main content

​
Config file locations

Monocle loads configuration from two locations in order — the project-level file overrides global settings:
  1. Global: ~/.config/monocle/config.json (or $XDG_CONFIG_HOME/monocle/config.json)
  2. Project: .monocle/config.json in your working directory

​
Full example

.monocle/config.json
{
  "layout": "auto",
  "diff_style": "unified",
  "sidebar_style": "flat",
  "wrap": false,
  "tab_size": 4,
  "context_lines": 3,
  "ignore_patterns": [],
  "min_diff_width": 80,
  "mouse": true,
  "auto_focus_mode": false,
  "keybindings": {},
  "review_format": {
    "include_snippets": true,
    "max_snippet_lines": 10,
    "include_summary": true
  }
}

​
Options

​
layout
string
default:"auto"
Pane arrangement. "auto" switches between side-by-side and stacked based on terminal width. "side-by-side" always uses the split view. "stacked" always stacks panes vertically.
​
diff_style
string
default:"unified"
Diff display mode. "unified" shows a single unified diff. "split" shows a side-by-side diff. "file" shows raw file content.
​
sidebar_style
string
default:"flat"
File list display mode. "flat" shows all files as a flat list. "tree" shows files in a collapsible directory tree.
​
wrap
boolean
default:"false"
Word-wrap long lines in the diff viewer. Toggle for the current session with w.
​
tab_size
integer
default:"4"
Number of spaces to render per tab character in diffs.
​
context_lines
integer
default:"3"
Number of unchanged lines shown above and below each diff hunk.
​
ignore_patterns
string[]
default:"[]"
Glob patterns for files to exclude from the diff view. For example: ["*.lock", "vendor/**"].
​
min_diff_width
integer
default:"80"
Minimum character width for the diff viewer in side-by-side layout. Below this width, Monocle switches to stacked layout.
​
mouse
boolean
default:"true"
Enable mouse interactions — click to focus panes, scroll with the wheel, click files to select, drag for visual selections, and interact with modal controls.
​
auto_focus_mode
boolean
default:"false"
Automatically enter focus mode (hide sidebar, enable line wrap) when reviewing plans submitted via monocle review send-artifact.
​
keybindings
object
default:"{}"
Custom key overrides. Map action names to key strings. See Custom keybindings below.

​
review_format

​
review_format.include_snippets
boolean
default:"true"
Include code snippets in the formatted review text delivered to the agent.
​
review_format.max_snippet_lines
integer
default:"10"
Truncate code snippets longer than this number of lines in the formatted review.
​
review_format.include_summary
boolean
default:"true"
Include a comment count summary (e.g. “2 issues, 1 suggestion”) at the end of the formatted review.

​
Custom keybindings

Override any action key by mapping the action name to a new key string in the keybindings object: 
{
  "keybindings": {
    "quit": "Q",
    "submit": "ctrl+s",
    "scroll_down": "ctrl+j"
  }
}
Toggle keybindings (T, t, w, f) change settings for the current session only. Edit the config file to persist your preferences.
Modal keys (Enter, Esc, Tab in overlays) are not configurable.

​
Available action names

ActionDefault keyDescription
upkMove up
downjMove down
topgJump to top
bottomGJump to bottom
half_upctrl+uScroll half page up
half_downctrl+dScroll half page down
prev_file[Previous file
next_file]Next file
prev_section{Previous sidebar section
next_section}Next sidebar section
selectEnterFocus diff pane / toggle directory
focus_swapTabSwitch pane focus
toggle_sidebar\Toggle sidebar visibility
scroll_downJScroll diff down
scroll_upKScroll diff up
scroll_lefthScroll diff left
scroll_rightlScroll diff right
scroll_home0Scroll to column 0
scroll_first_char^Scroll to first non-space
scroll_end$Scroll to line end
wrapwToggle line wrapping
toggle_difftCycle diff style
tree_modefToggle flat/tree view
collapse_allzCollapse all (tree)
expand_alleExpand all (tree)
commentcAdd/edit comment at cursor
file_commentCAdd file-level comment
suggestsSuggest edit at cursor
visualvVisual select (multi-line)
reviewedrToggle file reviewed
submitSSubmit review
pausePPause the agent
dismiss_outdated—Dismiss outdated comments
base_refbChange base ref
cycle_layoutTCycle layout
refreshRForce reload files
help?Show all keybindings
quitqQuit
command_mode:Enter command mode

​
Environment variables

​
MONOCLE_SOCKET
string
Override the Unix socket path used to connect to a running Monocle session. Useful when the agent’s working directory differs from Monocle’s. Set this in your agent’s environment or pass --socket on the CLI.
​
XDG_CONFIG_HOME
string
Override the base directory for the global config file. Defaults to ~/.config. The global config is read from $XDG_CONFIG_HOME/monocle/config.json.

Build docs developers (and LLMs) love

Get started for freeTalk to us