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, sandbox-mount, sandbox-env, sandbox-packages, sandbox-setup, sandbox-agents, 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`.
`terminal-background-opacity`	float	`1.0`	Per-terminal theme background alpha. Text and colored cell backgrounds stay opaque. 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-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.
`session-restore-lines`	int	`1000`	Lines of each pane's scrollback saved with the session and replayed into the pane on restore, so a restored window opens on the history it had. Colors and attributes come back with the text; images and live hyperlink targets do not. `0` restores the layout only.
`unified-tab-bar`	bool	`true`	Fold the tabs into the window titlebar, so the top row of tabs is the titlebar. Off gives an ordinary titlebar — window controls, the active tab's title, and the split buttons — with the tab bars beneath it. The split controls sit at the titlebar's right edge either way.
`tab-title-show-host`	bool	`false`	Keep the `user@host:` prefix shells write into their title. Off by default, so tabs show just the path. A label you set by hand is never rewritten.
`tab-peek`	bool	`true`	Allow the tab peek: a strip of live miniatures of every tab, dropped under the tab bar by `tab_peek` (⌘E) or the View menu. It covers the top of the terminal rather than resizing it, so nothing reflows.
`tab-peek-hover`	int	`0`	Milliseconds the pointer must rest on the tab bar before the peek drops on its own; it closes again when the pointer leaves. `0` means only the keybinding and the menu open it.
`tab-peek-height`	int	`120`	Height of a peek card in px (60–400). Card width follows each tab's own grid, so a card keeps the shape of the screen it shows.

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.

Agents

Key	Type	Default	Description
`mcp-server-enabled`	bool	`false`	Expose Sinclair's MCP server for tool calls.

Shared sandbox

One container per project, shared by your panes and every agent you run in them. Needs Docker or Podman and nothing else. See Share one container with your agents and Work in your project's dev container.

Key	Type	Default	Description
`sandbox-enabled`	bool	`false`	Run this project's panes and agents inside one shared container.
`sandbox-image`	string	none	Ready-made image, used as-is. Nothing is built; the image must carry the agent CLI.
`sandbox-base`	string	`debian:bookworm-slim`	Base image the generated sandbox image layers on. The generated layer uses `apt-get`.
`sandbox-packages`	string (repeatable)	none	Extra apt packages baked into the generated image.
`sandbox-setup`	string (repeatable)	none	Extra commands baked into the generated image, one layer each.
`sandbox-agents`	string (repeatable)	`claude`	Agent CLIs to install into the image: `claude`, `codex`, `gemini`.
`sandbox-mount`	string (repeatable)	none	Extra mounts, `source:target[:ro]`. A bare path mounts at itself.
`sandbox-env`	string (repeatable)	none	Extra environment inside the sandbox, `KEY=VALUE`.
`sandbox-user`	string	host uid on Linux	User the container runs as. `host` is your own `uid:gid`, which keeps a Linux bind mount from filling with root-owned files.
`sandbox-network`	string	`bridge`	`bridge`, `host`, or `none`. `none` cuts agents off from their model APIs.
`sandbox-memory`	string	unlimited	`--memory` ceiling for the whole sandbox, e.g. `8g`.
`sandbox-cpus`	string	unlimited	`--cpus` ceiling for the whole sandbox, e.g. `4`.
`sandbox-persist`	bool	`true`	Keep the container running when the last pane using it closes.
`sandbox-devcontainer`	bool	`true`	Read a project's `devcontainer.json`, and enter a container an editor already started for it.

Agents note

Note

The MCP server and the sandbox default to off. Turn them on only when you intend to use them — see the Agents and MCP pages for setup and details.