Otty Configuration Reference

Configuration file: ~/.config/otty/config.toml

Format: TOML — a flat list of key = value pairs (one per line, # for comments). Otty's reader is lenient, so quotes around simple string values are optional. Unknown keys are silently ignored, so a config written for a newer Otty stays loadable on an older build.

Most keys are also editable from Settings (the in-app UI writes the same file). A handful are Settings-only or theme-only and are noted as such.

---

Font

Key	Type	Default	Description
font-family	string | list	JetBrains Mono	Primary terminal font. Also accepts an inline array — font-family = ["A", "B"] — where the rest are fallbacks tried in order.
font-family-fallback	list	(none)	Extra fallback families tried, in order, before the OS system cascade. Comma-separated.
font-family-bold	string	(none)	Override family for bold cells. Empty = reuse font-family and synthesize.
font-family-italic	string	(none)	Override family for italic cells.
font-family-bold-italic	string	(none)	Override family for bold+italic cells.
font-family-fallback-bold	list	(none)	Per-style fallback chain for bold cells.
font-family-fallback-italic	list	(none)	Per-style fallback chain for italic cells.
font-family-fallback-bold-italic	list	(none)	Per-style fallback chain for bold+italic cells.
font-size	float	13.0	Font size in points.
font-blending	enum	srgb-over	Glyph alpha compositing. srgb-over blends in the gamma-encoded framebuffer (classic terminal look). macos-like keeps non-linear blending in the OS-native color space (Ghostty's native). linear blends in linear-light space (physically correct, can thin strokes). perceptual boosts alpha for thin strokes so dark text keeps its stem weight. Aliases: font-smooth, font-antialiased.
text-bold	enum	auto	How bold cells resolve when no bold face exists. Values: off, auto, primary-only, synthetic. Alias: font-bold.
text-italic	enum	auto	How italic cells resolve when no italic face exists. Values: off, auto, primary-only, synthetic. Alias: font-italic.
text-underline	bool	true	Render SGR-underline cells' underline decoration. Alias: font-underline.
text-blink	bool	false	Animate SGR-blink (SGR 5/6) cells. Off renders them steady (accessibility). Alias: font-blink.
font-ligatures	enum	dlig	OpenType ligature level. off disables programming ligatures, calt enables the standard/contextual set, dlig also enables discretionary ligatures. Alias: ligatures.
font-ligatures-alphabet	bool	false	Also form ligatures inside runs of letters/digits/CJK. Off keeps fi/fl-style letter ligatures from collapsing cells.
font-thicken	bool	false	macOS only. Force GUI-style stem darkening regardless of font-blending. Auto-enabled when background-opacity < 1.0. Mirrors Ghostty's font-thicken.
arrow-box-drawing-join	bool	true	Render arrows ← → ↑ ↓ and solid triangles ◀ ▶ ▲ ▼ aligned to the cell centerline when adjacent to a connecting rule (│, ─, ┃, ═, ┼, …) — arrows get a box-aligned stem + chevron, triangles a flat back flush on the rule's edge — so they butt against it instead of leaving a gap. Standalone glyphs in prose / TUIs are unaffected.
adjust-cell-height	string	(none)	Ghostty-compatible cell-height delta. Npx / bare N add logical points; N% scales by 1 + N/100. Negative compacts; glyphs stay vertically centered. Unset here, the active theme's [token].adjust-cell-height applies; unset in both, macOS/Linux use the font's natural line height and Windows defaults to line height 1.2 (20%), whose tight DWrite metrics otherwise render cramped rows. Set 0 to force the natural height anywhere.
live-resize-sigwinch-delay-ms	integer	50	Milliseconds the grid must stay stable during a live drag before a single mid-drag SIGWINCH fires. 0 disables the mid-drag signal (drag-end still fires one).

Cursor

Key	Type	Default	Description
cursor-style	enum	block	Cursor shape. Values: block, bar, underline, block_hollow (also block-hollow).
cursor-style-blink	enum	default_off	Cursor blink policy. Values: default_off, default_on, always_off, always_on. default_* set the initial blink but let a program override it (DECSCUSR blink bit / DEC mode 12); always_* pin it and ignore programs. Legacy true/false still parse as always_on/always_off.
cursor-color	color	(theme)	Cursor fill color.
cursor-text	color	(theme)	Text color under the cursor.
cursor-opacity	float	1.0	Cursor opacity (0.0 – 1.0).
cursor-animation	enum	off	Cursor motion animation. Values: off, smooth.

Shell & Environment

Key	Type	Default	Description
command	string	$SHELL (else /bin/zsh)	Shell/command to run. Alias: shell.
env	KEY=VALUE	(none)	Set an environment variable. Repeatable (one env line each).
term	string	auto	Value of $TERM. auto picks the best-supported value for Otty.
working-directory	enum | path	inherit	Initial directory. inherit, home, or an absolute path (~/ allowed).
window-working-directory	enum | path	profile	Directory for a brand-new window's first pane. profile (Windows only; elsewhere same as home) uses the launch profile's cwd (empty → home).
tab-working-directory	enum | path	inherit	Directory for a new tab (inherits the active pane's CWD).
split-working-directory	enum | path	inherit	Directory for a new split.

Terminal Identity & VT

Key	Type	Default	Description
enquiry-response	string	(empty)	Reply string for the ENQ (0x05) control character.
osc-color-report-format	enum	16-bit	OSC 4/10/11 color-query response format. Values: none, 8-bit, 16-bit.
title-report	bool	false	Allow apps to query the window title (XTWINOPS). Off by default (security).
vt-kam-allowed	bool	true	Allow the KAM (keyboard action mode) escape sequence.
vt-keypad-app-allowed	bool	true	Allow application keypad mode (DECKPAM, ESC =). When off, the keypad always sends literal digits.
kitty-keyboard	bool	true	Support the Kitty keyboard protocol (disambiguated/extended key reporting).
widen-ambiguous	list	(empty)	Unicode blocks whose East-Asian-Ambiguous codepoints render width-2. Empty by default so widths match your shell's wcwidth (ambiguous = 1 cell on macOS/Linux in every locale); only opt in if you run a CJK font whose programs also treat the range as wide, otherwise the cursor desyncs. Values: enclosed-alphanumerics, number-forms, math-operators, misc-technical, misc-symbols, dingbats, arrows, geometric-shapes.
login-greeting	bool	false	Run the login shell as a login shell so the system greeting/MOTD prints.

Scrollback & Session Log

Key	Type	Default	Description
scrollback-lines	integer	10000	Maximum scrollback lines retained per pane.
scrollback-limit	integer	(none)	Alternative byte-budget form (divided by 80 to derive lines). Mirrors Ghostty.
session-log-size-mb	integer	5	Max per-session log size (MB) used for recover & the scrollback pager.
session-log-mode	enum	redacted	Session log capture. plain stores raw output; redacted masks detected secrets with equal-width asterisks.
freeze-inactive-tab	bool	false	Release inactive tabs' GPU surfaces to save memory; recreate on switch. Off keeps tab switches smooth.

Session Restore

Key	Type	Default	Description
session-restore-banner	bool	true	Show "Closed at" / "Restored at" banners on restore.
session-restore-multiplayer	bool	true	Reattach multiplexer sessions (currently tmux) on restore.
session-restore-processes	enum	none	Which still-running pane commands to relaunch. Values: none, whitelist, all.
session-restore-process-allowlist	list	(none)	Command prefixes eligible for relaunch when session-restore-processes = whitelist. Matched as whitespace-delimited prefixes.
agent-command	AGENT=COMMAND	(built-in command)	Override the executable/wrapper and global arguments Otty uses to launch an agent. Repeat once per agent; Otty appends native resume/fork arguments.

For example, keep Claude Code's permission mode when Otty resumes or forks a session:

agent-command = claude=claude --dangerously-skip-permissions

The value before the second = is the agent id (claude, codex, opencode, cursor, kimi, pi, or omp). The command after it may include a wrapper, an absolute executable path, and global flags. Do not include --resume, the session id, or fork arguments—Otty adds those for the selected action. The same setting is available under Settings → Integrations → Coding Agents.

Window

Key	Type	Default	Description
window-size	enum	remember	How initial window size is decided. remember restores the last size, frame uses pixel dimensions, grid uses cell counts.
window-width-px	integer	1000	Initial window width in pixels (frame mode).
window-height-px	integer	600	Initial window height in pixels (frame mode).
window-cols	integer	80	Initial columns (grid mode).
window-rows	integer	24	Initial rows (grid mode).

Transparency

Applied at window creation; editing the value requires reopening the window.

Key	Type	Default	Description
background-opacity	float	1.0	Terminal background opacity (0.5 – 1.0). Values below 0.5 are rejected for readability.
window-opacity	float	1.0	Window-level opacity (0.5 – 1.0).
unfocused-split-opacity	float	0.6	Opacity of split panes that don't have focus (0.0 – 1.0). 1.0 keeps every pane fully visible — no dimming. Applies live; no window reopen needed.

Terminal Colors

Key	Type	Default	Description
foreground	color	#d4d4d4	Default text color (when no theme is set).
background	color	#1e1e1e	Terminal background color (when no theme is set).
palette-0 .. palette-15	color	(Dracula-based)	ANSI palette. 0–7 normal, 8–15 bright.
palette	N=COLOR	(none)	Alternative per-index syntax: palette = 1=#ff5555.
bold-color	enum | color	none	Bold text color. none, bright (use the bright palette variant), or a #rrggbb hex.
faint-opacity	float	0.5	Opacity multiplier for faint/dim text (0.0 – 1.0).
selection-foreground	color | auto	(none)	Text color in selections. Unset keeps the fg↔bg swap default; auto keeps each cell's original foreground.
selection-background	color	(none)	Selection background. Accepts 8-digit #rrggbbaa for a translucent selection. Unset uses the default foreground.
minimum-contrast	float	1.0	Minimum fg/bg contrast ratio (1.0 – 21.0). 1.0 disables adjustment.

Color values use hex format: #rrggbb (or #rrggbbaa where alpha is supported).

Default terminal colors only show when no theme is set. Out of the box Otty ships with theme = Paper, so the active colors come from that theme.

Fallback Palette

The 16-color palette used when no theme is active (Dracula-based):

Index	Color	Name		Index	Color	Name
0	#282a36	Black		8	#6272a4	Bright Black
1	#ff5555	Red		9	#ff6e6e	Bright Red
2	#50fa7b	Green		10	#69ff94	Bright Green
3	#f1fa8c	Yellow		11	#ffffa5	Bright Yellow
4	#bd93f9	Blue		12	#d6acff	Bright Blue
5	#ff79c6	Magenta		13	#ff92df	Bright Magenta
6	#8be9fd	Cyan		14	#a4ffff	Bright Cyan
7	#f8f8f2	White		15	#ffffff	Bright White

Theme

Key	Type	Default	Description
theme	string	Paper	Active theme (light slot). Overrides foreground, background, and palette. See Built-in Themes.
theme-dark	string	Nord	Theme used when the OS is in dark mode and auto-theme-dark-mode is on.
auto-theme-dark-mode	bool	true	Follow the OS appearance: theme for light, theme-dark for dark.

UI Chrome Colors

Control the application UI (sidebar, panels, borders). All optional; auto-derived from the terminal foreground/background when unset. Override the active theme's [panel].*.

Key	Type	Default	Description
ui-panel-background	color	(auto)	Chrome frame behind the terminal grid. (Not the app's main background — that's background.)
ui-panel-surface	color	(auto)	Surface/card background.
ui-panel-border	color	(auto)	Panel border. Accepts 8-digit #rrggbbaa for a translucent border.
ui-border-subtle	color	(auto)	Subtle/secondary border.
ui-text-primary	color	(auto)	Primary UI text.
ui-text-secondary	color	(auto)	Secondary UI text.
ui-text-tertiary	color	(auto)	Tertiary/muted UI text.
ui-hover	color	(auto)	Hover highlight.
ui-active	color	(auto)	Active/pressed highlight.
ui-accent	color	(auto)	Accent color (defaults to blue).

UI Font

Key	Type	Default	Description
ui-font-family	string	(system)	Font family for UI chrome text.
ui-font-size	float	13.0	Font size for UI chrome text in points.

Mouse & Input

Key	Type	Default	Description
mouse-reporting	bool	true	Forward mouse events to the terminal application.
mouse-hide-while-typing	bool	false	Hide the mouse cursor while typing.
mouse-scroll-multiplier	float | compound	3.0	Scroll speed for Otty's own scrollback. A single number sets both; compound form discrete:3.0,precision:1.0. Does not scale the wheel events sent to a program that reads the mouse itself (tmux, vim with mouse=a) — those apps apply their own step per event.
focus-follows-mouse	bool	false	Focus the pane under the mouse without clicking.
macos-option-as-alt	enum	false	Treat Option as Alt. Values: true, false, left, right.
shift-arrow-select	bool	true	Enable Shift+Arrow text selection.
mouse-shift-to-select	bool	true	Holding Shift always does local selection even when the app has mouse reporting on.
cursor-click-to-move	bool	true	Click on the active prompt line emits arrow keys to move the shell cursor to the click target.
right-click-action	enum	context-menu	What right-click does. Values: context-menu, copy, paste, copy-or-paste, ignore.
scroll-to-bottom	flags	keystroke,no-output	When to auto-scroll to bottom. Comma-separated: keystroke/no-keystroke, output/no-output.

Links & Open With

Key	Type	Default	Description
link-open-with	enum	browser	Where to open a clicked URL. Values: browser, otty.
file-open-with	enum	default-app	Where to open a clicked file path. Values: default-app, otty.
folder-open-with	enum	default-app	Where to open a clicked folder path. Values: default-app, otty.
link-schemes	enum	all	Which extra URL schemes are auto-detected. all (any scheme://) or custom (only the allowlist). http(s)/file/mailto are always detected.
link-scheme-allowlist	list	(none)	Extra schemes to detect when link-schemes = custom (bare names, no ://).
link-previews	bool	true	Show the corner pill with the hovered link's full URL — on Cmd-hover (macOS), on bare hover plus a Ctrl+Click to open hint (Windows). Off hides the pill only; links stay clickable.
open-with-app	Name|bundle	(none)	Add an external app to "Open in" submenus. Repeatable. Settings-managed.
open-with-command	Name|command	(none)	Add a TUI command (e.g. yazi, lazygit) to "Open in" submenus; it runs in a new tab rooted at the target. {} in the command is replaced by the target path. Repeatable. Settings-managed.
default-git-client	string	(auto)	Bundle ID of the preferred git GUI client for "Open in <App>". Empty = first installed.

Clipboard & Selection

Key	Type	Default	Description
clipboard-read	enum	ask	OSC 52 clipboard read access. Values: ask, allow, deny.
clipboard-write	enum	allow	OSC 52 clipboard write access. Values: ask, allow, deny.
clipboard-trim-trailing-spaces	bool	false	Trim trailing whitespace when copying.
copy-on-select	bool	false	Automatically copy on selection.
clipboard-paste-protection	bool	true	Warn before pasting potentially dangerous content.
clipboard-paste-bracketed-safe	bool	true	Sanitize bracketed-paste sequences inside pasted content.
selection-clear-on-typing	bool	true	Clear the active selection when typing.
selection-clear-on-copy	bool	true	Clear the selection after an explicit copy (does not apply to copy-on-select).
selection-backspace-deletes	bool	true	Backspace deletes a selection on the prompt line instead of one character at the cursor.

Sidebar & Layout

Key	Type	Default	Description
window-layout	enum	sidebar-left	Tab placement. Values: sidebar-left, tabs-top, tabs-bottom.
auto-hide-tab-bar	enum	default	Auto-hide policy for the inline tab bar (tabs-top/tabs-bottom). Values: always, default, auto. Alias: window-show-tab-bar.
auto-hide-tabs-panel	enum	default	Auto-hide policy for the sidebar tabs panel (sidebar-left). Same values.
sidebar-visible	bool	true	Show the sidebar on startup.
sidebar-width	integer	240 (220 on macOS)	Sidebar width in pixels. Also written back when you drag the sidebar's right edge.
details-panel-width	integer	220 (300 on Windows)	Details panel width in pixels. Also written back when you drag the details panel's left edge.

Tab Appearance

Edited in Settings → View; hand-editing is supported but the panel is easier.

Key	Type	Default	Description
title-from-osc	bool	true	Let programs rename the tab and window with OSC 0/1/2. Turn off to pin every tab to what the rules below resolve.
tab-rule	rule	(none)	One ordered rule per line, highest priority first. See below.
tab-icon-placement	enum	combined	Where a tab's icon sits. combined: it shares the badge slot, and a status badge takes over while one is active. separate: icon on the left, badges on the right, shell name hidden, and the window title carries the icon too.

A rule is a set of field="value" pairs on one line. The first four are match conditions — the Settings UI offers one per rule, but the file format accepts several and ANDs them; an omitted one means "don't care". The rest are what the rule contributes:

Field	Meaning
path	Glob against the pane's working directory. A pattern with no * also matches everything below it, so ~/Work/otty covers the whole project.
command	Glob against the foreground command line, e.g. ssh *.
agent	Coding agent bound to the pane: claude, codex, opencode, …
host	Glob against the SSH host of a remote session.
file	Glob against a file / folder / URL pane's name, e.g. *.md. Never matches a terminal pane, which has no file.
alias	Short project name, also available as ${alias} in titles.
icon	An icon name from the built-in set, or any emoji.
icon-color	Tint for the icon: an ANSI colour name (red, bright-blue, …) resolved against the active palette, or a literal #rrggbb. Empty = the tab's own text colour.
title	Title template — see the variables below.

Each of alias / icon / title is resolved independently: for each one, the first rule that matches and fills that field wins. A broad rule can supply the icon while a narrower rule above it overrides only the title.

Title templates interpolate ${alias}, ${cwd}, ${folder}, ${user}, ${host}, ${agent}, ${branch}, ${command}, ${title} (whatever the program set), ${shell}, ${file} and ${index}. A variable with no value expands to nothing, and a separator left stranded by it is dropped — ${folder} · ${branch} reads otty outside a repository, not otty ·.

Chain names with | for a fallback, first non-empty wins: ${title|folder} names the tab after its directory until a program sets a title. Any length works, and a quoted last link ends the chain in text rather than in a variable — ${title|file|folder|'Shell'}. Single quotes are the ones to reach for here: the template already lives inside a title="…" field, so double quotes would need escaping.

tab-rule = 'path="~/Work/otty" alias="Otty" icon="terminal" title="${alias} · ${branch}"'
tab-rule = 'path="~/Work/typora" alias="Typora" title="${alias}: ${title|folder}"'
tab-rule = 'agent="claude" icon="claude" icon-color="magenta"'
tab-rule = 'command="ssh *" icon="server" icon-color="cyan" title="${user}@${host}"'
tab-rule = 'file="*.md" icon="markdown" icon-color="blue"'

Matching is case-insensitive, ~ expands to your home directory, and * spans / so one wildcard can cover a whole tree.

Details Panel Views

Edited in Settings → View → Details Panel; see Details Panel.

Key	Type	Default	Description
details-view	view	(the four built-ins)	One view per line, in tab order. See below.
details-panel-width	int	220	Panel width in points.

Like tab-rule, a view is field="value" pairs on one line. Omit details-view entirely and you get Info, Outline, Git and Files in that order, all switched on; list any of them and the rest are appended after your entries, so a built-in added in a later release still shows up.

Field	Meaning
id	Required. A built-in (info, outline, git, files) or a name of your own, which also names the view's folder under ~/.config/otty/views/.
kind	builtin, tui (a program in an embedded terminal) or web (a URL). Inferred from url / command when omitted.
title	Tab label. Empty on a built-in keeps Otty's own translated name.
icon	An icon name from the built-in set, or any emoji. Empty uses the default glyph.
command	kind = tui: the whole command line, run the way a prompt would run it — pipes, && and ; included. ${…} variables resolve against the focused pane first: cwd, folder, file, pid, command, branch, host, user, agent, shell. Substitution is textual, so quote a value that may contain spaces.
url	kind = web: the page to load.
mobile	kind = web: false asks the site for its desktop page. On by default — the panel is a narrow column, and a mobile layout is what fits it. The page is laid out at the panel's width either way.
cwd	kind = tui: where to run it. Empty = ~/.config/otty/views/<id>, created on first launch.
enabled	false hides the tab without forgetting how it was set up.

details-view = 'id="info"'
details-view = 'id="docker" kind="tui" title="Docker" command="lazydocker" icon="docker"'
details-view = 'id="lazygit" kind="tui" title="Git" command="lazygit -p \"${cwd}\""'
details-view = 'id="grafana" kind="web" title="Grafana" url="http://localhost:3000"'
details-view = 'id="admin" kind="web" url="http://localhost:8080" mobile="false"'
details-view = 'id="outline"'
details-view = 'id="git" enabled="false"'

Two tui views that resolve to the same command and folder share one running program across every window — so a ${cwd} view gets one program per directory. At most six are kept alive; the least recently used is retired.

A tui view runs with OTTY_NO_NEW_PANE=1 and a shimmed PATH: it may not open Otty windows, tabs or panes, and open / xdg-open are refused. otty view / otty edit still work — inside a view they load into that view. See Details Panel.

Shell Integration & CLI

Key	Type	Default	Description
shell-integration	bool	true	Install the managed shell-rc block (OSC 133 marks, CWD reporting, edit/view/jump wrappers, custom aliases).
ssh-integration	bool	true	Forward Otty's shell integration over SSH to remote hosts.
omit-otty-prefix	bool	false	Install edit/view/watch shell functions so the otty prefix can be dropped. Live-toggleable.
cli-allow-overwrite	bool	false	Let omit-prefix / custom-alias wrappers replace names the user already defined.
cli-alias	name=cmd	(none)	User CLI alias: installs a shell function <name> running otty <command>. Repeatable. Settings-managed.
progress-bar-commands	list	(built-in set)	Command prefixes the shell integration auto-emits OSC 9;4 progress for (curl, git push, npm install, …). Matched as whitespace-delimited prefixes.

App Behavior

Key	Type	Default	Description
language	enum	system	UI language. Values: system, english, chinese.
on-launch	enum	restore_session	What happens at launch. Values: new_window, restore_session.
quit-after-last-window-closed	bool	false	Quit Otty when the last window closes.
stay-in-tray	bool	false	Windows only. Keep Otty running after the last window closes, reachable from the tray icon.
show-tray-icon	bool	true	Windows only. Show the notification-area (tray) icon. Forced on while stay-in-tray is set.
quick-access	list	—	Pinned entries for the + menu, the tray menu and the Jump List, one per line: quick-access = 'kind="folder" value="C:\dev\otty" label="otty"'. kind is folder, recipe, ssh or profile; value is the path, recipe id, ssh host or profile id.
confirm-close-tab	enum	process	Confirm closing a tab. Values: always, process (only with a running process), never.
confirm-close-window	enum	process	Confirm closing a window. Values: always, process, multiple_tabs, never.
confirm-close-pane	enum	process	Confirm closing a split pane. Values: always, process, never.
window-hide-dirty-indicator	bool	false	macOS only. Never show the unsaved/running dot on the window close button (traffic light).
new-tab-position	enum	auto	Where a new tab opens. Values: end, auto, after-current.

Autocomplete

Key	Type	Default	Description
autocomplete-shortcut	enum	tab	Key that accepts a suggestion. Values: tab, tab+right-arrow, ctrl+space, disable.
autocomplete-show-candidates	enum	escape	Key that reveals the candidate panel. Values: disable, auto, escape, option-escape.
autocomplete-inline-suggestion	bool	true	Show a faded inline preview when one suggestion clearly leads: the only match, a whole command line that leads this folder, or — in tab+right-arrow — the top of several.
autocomplete-on-device-learning	bool	true	Allow on-device learning (history, --help probes, README extraction). Privacy gate; everything stays local.
autocomplete-skip-secrets	bool	false	Never record a command that looks like it carries a password, token or API key. New commands only — already-stored ones are untouched, and otty learn still keeps one deliberately.
autocomplete-history-ignore	list	(none)	Glob patterns for commands never recorded (e.g. ssh *, export *TOKEN*).
autocomplete-description-language	enum	system	Language for spec descriptions. Values: system, english, chinese.

Notifications, Sounds & Badges

Defaults for new panes. Most are per-pane overridable at runtime.

Key	Type	Default	Description
notification-foreground	enum	off	Banner behavior while Otty is foreground. Values: off, always, tab-unfocused.
privilege-sound-on-error	bool	false	Play a sound on a non-zero command exit.
privilege-sound-shell	bool	true	Let shell-integration commands trigger sounds.
privilege-notification-on-finish	bool	false	Notify when a long command finishes.
privilege-notification-on-error	bool	true	Notify when a command errors.
privilege-notification-on-watch-finish	bool	true	Notify when a watched command finishes.
privilege-notification-shell	bool	true	Let shell-integration commands post notifications.
privilege-badge-exit-status	bool	true	Show an exit-status badge on the tab.
privilege-badge-activity	bool	true	Show an activity badge for background output.
privilege-badge-agent-processing	bool	true	Badge while an agent is processing.
privilege-badge-agent-task-complete	bool	true	Badge when an agent finishes a task.
privilege-badge-agent-awaiting-input	bool	true	Badge when an agent awaits input.
privilege-notify-agent-task-complete	bool	true	System notification when an agent finishes a task.
privilege-notify-agent-awaiting-input	bool	true	System notification when an agent awaits approval/input.
privilege-caffeinate-agent-processing	bool	false	Keep the Mac awake while an agent is processing.
privilege-resume-agent-session	bool	true	Offer to resume agent sessions on restore.
privilege-mouse-shell	bool	true	Let the shell control mouse reporting.
privilege-title-shell	bool	true	Let the shell set the window/tab title.
privilege-clipboard-shell	bool	true	Let the shell drive clipboard (OSC 52) operations.

Auto Approve & IPC Security

Key	Type	Default	Description
show-auto-approve	bool	false	Surface the (deprecated) Auto Approve feature in the UI.
auto-approve-enabled	bool	false	Enable Auto Approve.
hide-auto-approve-pill	bool	false	Hide the Auto Approve toolbar pill.
ipc-allow-send-keys	bool	false	Allow the send-keys IPC command.
ipc-allow-sensitive-sessions	bool	false	Allow send-keys/capture on SSH/sudo sessions.

Secure Input (macOS)

Key	Type	Default	Description
auto-secure-input	bool	true	Auto-enable macOS Secure Keyboard Entry at password-style prompts.
secure-input-indication	bool	true	Show the title-bar pill while Secure Keyboard Entry is active.

Quick Terminal

Key	Type	Default	Description
quick-terminal-persist-session	bool	false	Keep the quick-terminal session alive between toggles.
quick-terminal-cwd	enum	current-pane	Working directory for the quick terminal. Values: last-used, current-pane.

Recipes

Key	Type	Default	Description
recipe-replay-saved	enum	ask_once	Command replay for internally-saved recipes. Values: auto, ask_once, manually.
recipe-replay-file	enum	manually	Command replay for external .ottyrecipe files. Same values.

See Custom Commands / Layouts / Snippets and Recipes.

Open Quickly, Frecency & Jump

Key	Type	Default	Description
open-quickly-folders-limit	integer	12	Max frecency-ranked folders surfaced in Open Quickly. Alias: open-quickly-zoxide-limit.
frecency-auto-record	bool	true	Record every CWD change into the frecency table (powers the Folders tab and otty jump).
zoxide-enabled	bool	true	Sync removals to the external zoxide binary when present.
zoxide-local-path	string	(auto)	Explicit path to the zoxide binary. Empty = auto-detect. Settings-hidden.

Editor (File Pane)

Apply to Otty's non-terminal text surfaces (file panes, previews).

Key	Type	Default	Description
editor-line-wrap	bool	true	Soft-wrap long lines instead of horizontal scrolling.
editor-tab-size	integer	4	Visual width of a tab character, in columns.
editor-visible-whitespace	bool	false	Render whitespace as glyphs.
editor-show-line-numbers	bool	true	Show the line-number gutter.
editor-default-to-preview-readonly	bool	true	Open preview-capable formats (.md, .svg, .html…) in read-only preview mode.
editor-scroll-past-end	bool	true	Allow scrolling past the last line (VS Code's scrollBeyondLastLine).

Terminal Scrolling

Key	Type	Default	Description
terminal-scroll-past-end	enum	disabled	Scroll past the last line in the terminal. Values: disabled, last-line-with-content, last-line-in-middle, cursor-line. Always off on the alternate screen.
terminal-scroll-past-first-line	enum	disabled	Scroll past the first scrollback line. Values: disabled, same-as-last-line, first-line-with-content, first-line-in-middle.
terminal-scroll-past-end-sticky	bool	false	Keep the past-end offset sticky instead of draining it as new output arrives.
terminal-scroll-smooth	bool	true	Pixel-granular scrollback navigation; snaps to the nearest row on idle.
terminal-scrollbar-hide-on-auto-scroll	bool	false	Show the scrollbar only while the viewport is parked away from the live output; keep it hidden while the view just follows program output.

Dock Icon (macOS)

Key	Type	Default	Description
dock-icon-animate-progress	bool	false	Animate the Dock icon while any session emits OSC 9;4 progress.
dock-icon-error-badge	bool	true	Tint the Dock icon red on a non-zero exit / OSC 9;4;2 error; clicking focuses the next error tab.

Keybindings

Key	Type	Default	Description
keybind	trigger=action	(built-in)	Bind a key chord to an action. Repeatable. See the Keybindings Reference for triggers and action names.

---

Built-in Themes

Set a theme with theme = <name> (case-insensitive). The theme overrides foreground, background, and the 16-color palette. theme-dark selects a separate dark-mode theme when auto-theme-dark-mode is on.

Acrylic Dark	Glass Light	Owl
April	Gruvbox Dark	Paper
April Dark	Monokai Classic	Pink
Ayu Dark	Newsprint	Rosé Pine
Ayu Light	Night	Seafoam Pastel
Catppuccin Mocha	Nord	Solarized Dark
Dracula	One Dark	Solarized Light
Floating Card	One Light	Tokyo Night
Glass Dark

The defaults differ per platform: macOS and Linux open on Paper / Nord (light / dark), Windows on One Light / Acrylic Dark — the two themes carrying the Windows chrome treatment.

You can also drop custom .toml themes into ~/.config/otty/themes/ or import them from other terminals — see Themes and Import / Export Settings.

---

Example Configuration

# Otty config example
theme = Dracula
font-family = JetBrains Mono
font-size = 14

# Semi-transparent background (minimum 0.5)
background-opacity = 0.9

# Cursor
cursor-style = bar
cursor-style-blink = default_on

# Use Option as Alt for both keys
macos-option-as-alt = true

# Environment
env = EDITOR=nvim

# Scrollback
scrollback-lines = 50000

See also

• Config File — where these keys live and how to edit them.
• Config File Format — the TOML key = value syntax and value types.
• Keybindings Reference — the default keybind map.
• Theme Format — the separate TOML schema for theme files.