Configuration

Sinclair reads a single settings.json — JSON with // comments. Appearance and keybindings reload the instant you save it — no restart required.

Where the config lives

Sinclair loads its settings from $XDG_CONFIG_HOME/sinclair/settings.json, falling back to ~/.config/sinclair/settings.json when XDG_CONFIG_HOME is unset (Windows: %APPDATA%\sinclair\settings.json). The file is created on demand, so you can start from an empty {} (or no file at all) and add only the keys you care about. A legacy key = value config file from older versions is migrated into settings.json once on launch and no longer read.

If you would rather not edit text by hand, open the built-in GUI settings with ⌘, and the same options are exposed there.

Format

The file is JSON with comments: one object, one member per setting. // comment lines are allowed and ignored.

Most keys take a single scalar value. A handful of keys are lists and take a JSON array, one entry per value. The list keys are font-family, font-feature, keybind, palette, plugin, container, agent-custom, redact, trigger, snippet, and profile.

Bad lines never abort the load. An unknown key, a malformed value, or a typo becomes a friendly diagnostic surfaced on startup, and the rest of the file is applied normally.

// ~/.config/sinclair/settings.json
{
  "font-family": ["JetBrains Mono", "Menlo"],   // fallback chain, in order
  "font-size": 14,
  "font-feature": ["+liga", "ss01"],

  "theme": "Catppuccin Mocha",
  "cursor-style": "bar",
  "copy-on-select": true,
  "scrollback-limit": 50000
}

Live reload

Sinclair watches the config file. Appearance settings (fonts, theme, colors, padding, cursor) and keybindings take effect the moment you save — there is no need to quit and relaunch.

Tip

Keep the config open in a split next to a live terminal and tweak fonts or themes interactively — each save redraws immediately.

Options

Every supported key is listed below, grouped by area. Keybindings have their own syntax and reference; see the Keybindings page for the keybind option.

Fonts & text

Key	Type	Default	Description
`font-family`	string (repeatable)	`Menlo`	Primary font; repeat to build a fallback chain in order of preference.
`font-size`	float	`13.0`	Font size in points.
`font-style`	enum `normal`\|`bold`\|`italic`\|`bold-italic`	`normal`	Base style applied to the default text.
`font-feature`	string (repeatable)	none	OpenType feature codes, e.g. `+liga`, `-calt`, `ss01`, `cv01=2`.
`adjust-cell-width`	int	`0`	Pixels added to (or removed from) each cell's width.
`adjust-cell-height`	int	`0`	Pixels added to (or removed from) each cell's height.

Theme & colors

Key	Type	Default	Description
`theme`	string	`Dark`	Built-in or custom theme name. Matching is case-, space-, dash-, and underscore-insensitive.
`theme-light`	string	none	Theme used when the OS is in light mode. Set with `theme-dark` to follow the system appearance automatically (live).
`theme-dark`	string	none	Theme used when the OS is in dark mode.
`background-opacity`	float	`1.0`	Window background alpha; the terminal goes translucent. Clamped to `0.2..=1.0`.
`background-image`	path	none	Image drawn behind the terminal (best with `background-opacity` < 1 so it shows through).
`badge`	string	none	Faint watermark drawn in each pane's corner; `{cwd}` and `{host}` are substituted per pane.
`background`	hex	none	Override the theme background color.
`foreground`	hex	none	Override the theme foreground color.
`bold-is-bright`	bool	`false`	Render bold text using the bright ANSI palette variant.
`minimum-contrast`	float	`1.0`	Minimum foreground/background contrast ratio. Clamped to `1..=21`.
`split-divider-color`	hex	none	Color of the divider between splits.
`unfocused-split-opacity`	float	`0.7`	Opacity of splits that are not focused. Clamped to `0.15..=1.0`.
`palette`	string (repeatable)	none	Override a single ANSI color as `N=#rrggbb`, where `N` is index 0–255.

Cursor

Key	Type	Default	Description
`cursor-style`	enum `block`\|`bar`\|`underline`	`block`	Shape of the text cursor.
`cursor-style-blink`	bool	`true`	Whether the cursor blinks.
`cursor-color`	hex	none	Override the cursor color.
`cursor-text`	hex	none	Color of the glyph under the cursor.
`selection-foreground`	hex	none	Text color within a selection.
`selection-background`	hex	none	Background color of a selection.

Window & padding

Key	Type	Default	Description
`window-padding-x`	int	`2`	Horizontal padding (pixels) between the grid and the window edge.
`window-padding-y`	int	`2`	Vertical padding (pixels) between the grid and the window edge.
`window-width`	int (cells)	`0` (80)	Initial window width in cells; `0` means 80.
`window-height`	int (cells)	`0` (24)	Initial window height in cells; `0` means 24.
`title`	string	none	Fixed window title; overrides the title set by the running program.
`quit-after-last-window-closed`	bool	`false`	Quit the app once the last window closes.
`window-inherit-working-directory`	bool	`true`	New windows inherit the working directory of the focused surface.
`mouse-scroll-multiplier`	float	`1.0`	Scroll speed multiplier. Clamped to `0.01..=10000`.
`mouse-hide-while-typing`	bool	`false`	Hide the mouse cursor while you type.
`smart-select`	bool	`true`	Double-click selects the whole URL / email / path / git hash under the pointer, falling back to a word.
`middle-click-paste`	bool	`false`	Paste the current selection with a middle click (X-style).
`focus-follows-mouse`	bool	`false`	Focus the split the pointer moves over, without a click.
`macos-option-as-alt`	enum `auto`\|`left`\|`right`\|`true`\|`false`	`auto`	Treat the macOS Option key as Alt for key encoding.

Shell & behavior

Key	Type	Default	Description
`command`	string (shell path)	none (login shell)	Program to run instead of the default login shell.
`working-directory`	string	none (`$HOME`)	Initial working directory for new surfaces.
`copy-on-select`	bool	`false`	Copy selected text to the clipboard automatically.
`timestamps`	bool	`false`	Show a faint relative time (5s/2m/1h/3d) beside each scrollback row.
`confirm-close-surface`	bool	`true`	Sinclair before closing a surface that has a running process.
`confirm-quit`	bool	`true`	Sinclair before quitting the application.

Clipboard & scrollback

Key	Type	Default	Description
`clipboard-read`	enum `allow`\|`ask`\|`deny`	`ask`	Policy for programs reading the clipboard.
`clipboard-write`	enum `allow`\|`ask`\|`deny`	`allow`	Policy for programs writing the clipboard.
`clipboard-paste-protection`	bool	`false`	Warn before pasting potentially unsafe content.
`scrollback-limit`	int (lines)	`100000`	Maximum number of scrollback lines retained.

Shell integration & sessions

Key	Type	Default	Description
`shell-integration`	bool	`true`	Inject OSC 133 prompt marks and OSC 7 cwd reporting into zsh/bash/fish via environment — no rc-file edits.
`auto-update`	bool	`true`	Check GitHub for a newer release on launch and hourly, and offer to update (Homebrew/apt installs defer to the package manager; manual .dmg/AppImage swap in place).
`autosuggest-ghost`	bool	`true`	Fish-style inline ghost text completing the current command; accept with → or End. Needs shell integration.
`autosuggest-popup`	bool	`false`	Show a completion dropdown under the cursor; ↑/↓ to move, Enter to accept.
`autosuggest-tab`	bool	`false`	Tab cycles inline completions instead of forwarding Tab to the shell.
`autosuggest-ai`	bool	`false`	When nothing local matches, ask Claude for a next-command suggestion (needs AI enabled).
`autosuggest-history`	bool	`true`	Use captured command history as a suggestion source.
`autosuggest-commands`	bool	`true`	Use the built-in common-command list as a suggestion source.
`autosuggest-paths`	bool	`true`	Complete filesystem paths from the working directory.
`autosuggest-assist`	bool	`true`	Rank suggestions with the local assist model rather than plain recency.
`session-restore`	bool	`false`	Restore windows and splits from the previous run.
`tab-title-show-host`	bool	`false`	Show the hostname in tab titles.

Automation & privacy

Key	Type	Default	Description
`trigger`	string (repeatable)	none	Regex, optionally `regex \| Title`. When new output matches, a desktop notification fires with the matched line.
`redact`	string (repeatable)	none	Regex whose matches are masked with bullets on every copy path, keeping secrets off the clipboard.
`snippet`	string (repeatable)	none	`label \| command`; recalled from the snippet picker (`snippets` action), inserted into the focused pane.
`profile`	string (repeatable)	none	`label \| command`; opens a new tab running the command from the profile picker (`profiles` action).

Plugins

Key	Type	Default	Description
`plugin`	string (repeatable)	none	Path to a plugin directory or a `plugin.toml` file. `~` expands to the home directory.

AI & relay

Key	Type	Default	Description
`ai-enabled`	bool	`false`	Master switch for AI features.
`ai-optimize-tokens`	bool	`false`	Compact prompts sent to agents (whitespace collapsed, terse relay harness) to spend fewer tokens.
`mcp-server-enabled`	bool	`false`	Expose Sinclair's MCP server for tool calls.
`relay-enabled`	bool	`false`	Enable the agent mesh relay integration.
`relay-start-on-launch`	bool	`false`	Start the relay daemon when the app launches.
`relay-address`	string	`127.0.0.1:7777`	Address the relay server listens on.
`relay-default-agent`	string	`claude`	Default agent launched into a relay split.

Agents

Key	Type	Default	Description
`agent-claude`	bool	`true`	Enable the Claude Code agent.
`agent-codex`	bool	`false`	Enable the Codex agent.
`agent-ollama`	bool	`false`	Enable the Ollama agent.
`agent-gemini`	bool	`false`	Enable the Gemini agent.
`agent-claude-path`	string	none	Explicit path to the Claude Code executable.
`agent-codex-path`	string	none	Explicit path to the Codex executable.
`agent-gemini-path`	string	none	Explicit path to the Gemini executable.
`agent-claude-args`	string	none	Extra CLI flags appended when launching Claude Code, e.g. `--dangerously-skip-permissions`. Quote values with spaces.
`agent-codex-args`	string	none	Extra CLI flags appended when launching Codex.
`agent-gemini-args`	string	none	Extra CLI flags appended when launching Gemini.
`agent-custom`	string (repeatable)	none	Custom agent as `label\|command template`, with `{prompt}`, `{mcp}`, `{url}`, and `{name}` placeholders.

AI & relay note

Note

All AI, relay, and agent options default to off. Turn them on only when you intend to use them — see the Agent mesh and MCP pages for setup and details.