Otty Configuration Reference

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

Format: Ghostty-style key = value (one per line, # for comments). Despite the .toml extension the file is line-based, not real TOML — values are bare (quotes are optional and stripped). 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.
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	bool	(app default)	Whether the cursor blinks. Unset follows the application's request.
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	home	Directory for a brand-new window's first pane.
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	enclosed-alphanumerics	Unicode blocks whose East-Asian-Ambiguous codepoints render width-2. 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.

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).

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. A single number sets both; compound form discrete:3.0,precision:1.0.
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.
open-with-app	Name|bundle	(none)	Add an external app to "Open in" submenus. 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	false	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	220	Sidebar width in pixels.
details-panel-width	integer	220	Details panel width in pixels.

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.
confirm-close-tab	enum	process	Confirm closing a tab. Values: always, process (only with a running process).
confirm-close-window	enum	process	Confirm closing a window. Values: always, process, multiple_tabs.
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 there's a single suggestion.
autocomplete-on-device-learning	bool	true	Allow on-device learning (history, --help probes, README extraction). Privacy gate; everything stays local.
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.

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.

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

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 = true

# 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 key = value syntax and value types.
• Keybindings Reference — the default keybind map.
• Theme Format — the separate TOML schema for theme files.