Customize

Configuration

One JSON file holds everything. The settings window edits the same file.

Two ways in

g, or Cmd+, opens the settings window. Every change is written to ~/.config/lean/config.json and applies at once.

Cmd+Opt+, opens the file itself. Projects, URL rules, environments and your own commands are edited there. After saving, gr reloads it. If the file has a mistake, Lean says so and runs with the default settings until the file is fixed; the file itself is left as it is.

General

Key	Default	Does
`homepage`	`about:blank`	the page of a new tab
`searchUrl`	DuckDuckGo	where text that is not an address goes; `%s` is the text
`hintChars`	`asdfghjkl`	the letters used for link labels
`scrollStep`, `smoothScroll`		how far and how `j` and `k` scroll
`pageZoom`		zoom of all pages
`mcpPort`	`8719`	port of the server for Claude Code; `0` turns it off. Read at start only.

Tabs and sidebar

Key	Default	Does
`liveTabs`	`8`	tabs that stay awake
`autoSuspendMinutes`	`0`	puts tabs to sleep after this time; 0 is off
`sidebarWidth`	`270`	in points; dragging the sidebar's edge sets it
`clusterTabs`	on	tabs of one kind together inside a group
`jiraHost`	empty	host whose issue tabs show their status
`groupIssuesByProject`	on	issue tabs go into the group named like their key
`jiraStatusWhenSuspended`	on	sleeping issue tabs keep their status
`projects`, `environments`		see Projects and tabs

Look

Key	Does
`theme`	a Ghostty theme name, `ghostty`, `random`, or `light:Name,dark:Name`. See Themes.
`fontFamily`, `fontSize`	font of sidebar and status line; `ghostty` uses the font of your Ghostty config
`opacity`	0.3 to 1; below 1 the sidebar and status line show the blurred desktop
`paintPages`	repaints every page in the theme colours
`accentFromProject`	selection and loading bar take the current project's colour

Keys and commands

Key	Does
`keys`	key sequence to action, merged over the defaults. See Changing keys.
`commands`	command to action, merged over the defaults. See Your own commands.

Passwords

Key	Default	Does
`protonPass`	off	turns on filling logins from Proton Pass
`passTouchId`	on	asks for Touch ID before the vault is used
`passAuthMinutes`	`5`	how long one Touch ID confirmation holds
`passLogoutMinutes`	`60`	signs out after this time without a fill; 0 never
`passLogoutOnQuit`	on	signs out when Lean quits
`passboltUrl`, `passboltApp`, `passboltProfile`		where the Passbolt hand-off goes
`clipboardClearSeconds`	`30`	wipes a copied password from the clipboard after you return

The same config on every Mac

Put config.json into your dotfiles and link it into ~/.config/lean/. With GNU Stow, use stow --no-folding, so the folder stays a real folder and only the config is a link. The session, the token and the Proton Pass sign-in then stay on each Mac, where they belong.

The config names your hosts and projects. Keep it out of public repositories if those are not public knowledge.