Settings

⌘, opens Settings as a tab, not a window — it sits after your terminal tabs, and choosing any terminal tab uncovers it again. Ghostty’s own ⌘, (open_config) opens the same tab. ⌘W while it shows closes only it.

Every section switches between controls and the JSON behind them. The two files are

~/Library/Application Support/Overterm/settings.json
~/Library/Application Support/Overterm/keybindings.json

— VS Code’s two files, in VS Code’s spirit. See keybindings.json for the second one.

How settings.json behaves

• Only what you changed is in it. A setting at its default is not written, so the file stays short and readable.
• It is JSON5. Comments and trailing commas are allowed. Your comments and your key order survive: the app edits a key’s own line in place, and only rewrites the file whole if it is not laid out one key per line.
• A hand edit applies immediately. The file is watched; saving it in an editor takes effect without relaunching.
• A file that does not parse is never written over. The last good settings stay in force and the page says what is wrong.
• A value that does not fit its setting is listed and the default applies. An unknown key is listed and left alone.

Appearance, Themes and Terminal are Ghostty’s own settings. Left unset, your own ~/.config/ghostty/config decides. Set, they are written to ghostty-overrides.conf beside settings.json, which Overterm loads after your config, and every open terminal is handed the new configuration at once — no relaunch. Your own file is never edited.

Before version 1.17 these lived in UserDefaults; they are carried over once, automatically.

General

Key	Default	What it does
general.restoreTabs	true	Reopen the last session’s tabs. Agent tabs resume their conversation rather than restoring text.
general.restoreScrollback	true	…with each shell pane’s text, saved when Overterm quits. Needs general.restoreTabs.
general.scrollbackLines	2000	Lines of text kept per pane and brought back at launch. 100–20000. Needs general.restoreScrollback.
general.newTabDirectory	"current"	Where new tabs open: "current" (the current tab’s folder) or "home".
general.confirmClose	"always"	Ask before closing tabs, the window and quitting: "always" or "whenRunning". A pane of a split asks only when something runs in it.
general.usageChip	true	Show the quota gauge at the right of the tab strip.
general.usageAsk	true	Run the agent’s own usage command every ten minutes while Overterm is in front. Off, the pane shows the last figures the agent wrote down and their age.
general.usageCost	true	Price the tokens in the agents’ own logs at list API rates. An estimate, not your bill.
general.overgitCommits	300	How many commits Overgit’s history and graph read. 50–2000.
general.overgitAllRefs	false	Graph every branch and tag, so unmerged branches appear.
general.tabPeekGesture	"three"	The Tab Peek swipe: "three", "four" or "off". ⇧⌘E and ⎋ work whatever this says.

Appearance

Every key here is unset by default, which means your Ghostty config decides.

Key	Default	What it does	Ghostty option
appearance.fontFamily	unset	The terminal font, from this Mac’s monospaced fonts	font-family
appearance.fontSize	unset	Font size, 8–32 pt	font-size
appearance.fontThicken	unset	Draws text a little bolder, as some prefer on light backgrounds	font-thicken
appearance.windowPadding	unset	Padding around the text, 0–40 pt	window-padding-x, window-padding-y
appearance.cursorStyle	unset	"block", "bar" or "underline"	cursor-style
appearance.cursorBlink	unset	Blinking cursor	cursor-style-blink
appearance.unfocusedPaneDim	0.35	How much the panes without the keyboard are dimmed, 0–0.7	—

Themes

Key	Default	What it does	Ghostty option
appearance.theme	unset	The theme. The terminal and everything around it change at once.	theme
appearance.followSystemAppearance	unset	Follow macOS between a light and a dark theme, with no relaunch.	theme
appearance.themeLight	unset	The light theme, used while macOS is light. Needs the switch above.	theme

All three write the one theme option: on its own it is a name, and with the system switch on it is a light:…,dark:… pair that Ghostty switches between itself. See Themes.

Terminal

Unset by default, so your Ghostty config decides.

Key	Default	What it does	Ghostty option
terminal.optionAsAlt	unset	Option acts as Alt: "false", "true", "left" or "right". For Emacs and readline’s word movement; off, ⌥ types its characters.	macos-option-as-alt
terminal.copyOnSelect	unset	"false" or "clipboard"	copy-on-select
terminal.hideMouseWhileTyping	unset	Hide the pointer while typing	mouse-hide-while-typing
terminal.scrollbackMegabytes	unset	Scrollback per pane, 1–500 MB	scrollback-limit (in bytes)
terminal.clipboardRead	unset	A program reading the clipboard (OSC 52): "ask", "allow" or "deny". Asking shows what it would get first.	clipboard-read
terminal.pasteProtection	unset	Ask before pasting text that could run commands	clipboard-paste-protection

Agents

Key	Default	What it does
agents.claudeArguments	""	Added wherever Claude starts or resumes: ⌥⌘C, New Task, tabs reopened at launch, and Sessions’ resume. For example --model opus.
agents.codexArguments	""	The same for Codex, for example -m gpt-5.
agents.newTaskAgent	"claude"	What New Task starts: "claude", "codex" or "shell".
agents.worktreeLocation	"sibling"	Where a task’s worktree goes: "sibling" (repo-wt-branch) or "inside" (repo/.worktrees/branch). Inside, .worktrees/ is added to .git/info/exclude — no tracked file changes.
agents.newTaskBase	""	What new branches start from. Empty means the main worktree’s branch.

Editor

Key	Default	What it does
editor.fontFamily	""	Empty means the system’s monospaced font.
editor.fontSize	13	9–28 pt
editor.lineHeight	"comfortable"	"compact", "standard" or "comfortable" (Zed’s).
editor.softWrap	"prose"	"none" (scroll sideways), "prose" (Markdown and text files) or "always".
editor.tabSize	4	Tab width in columns, 1–16. A file’s own indentation wins: one indented with 2 spaces keeps 2.
editor.indentGuides	true	Indent guides
editor.openZoomed	false	Off, a file opens beside the terminal and ⇧⎋ zooms it. On, the editor takes the terminal’s place.
editor.gitGutter	true	Mark lines changed since the last commit
editor.languageServers	true	Completions, problems, hover and go to definition from language servers on your PATH or ones Zed downloaded.
editor.completions	true	Show completions as you type. ⌃Space shows them either way.
editor.formatOnSave	false	Format on save with the language server’s formatter. Needs editor.languageServers.
editor.vimMode	false	Vim mode, as Zed’s: yanks go to the clipboard.
editor.relativeLineNumbers	false	Relative line numbers

Browser

Key	Default	What it does
browser.enabled	true	A browser column beside the terminal, one per tab. Off: no column, and links open in your own browser.
browser.openLinks	"local"	Where a link clicked in the terminal opens: "local" (here when it is on this machine, else your browser), "all", "none". Needs browser.enabled.
browser.reloadOnSave	false	Reload a local page when a file is saved — in the editor, or by an agent in the checkout. Needs browser.enabled.
browser.agentControl	true	Claude Code started from Overterm gets an MCP server for its tab’s browser. Needs browser.enabled.

See Browser and MCP.

Notifications

Key	Default	What it does
notifications.enabled	true	Notify while Overterm is in the background
notifications.waiting	true	…when an agent waits for you. Needs notifications.enabled.
notifications.finished	true	…when work finishes: an agent done, or a command that ran 10 s or more. Needs notifications.enabled.
notifications.failed	true	…when something fails. Needs notifications.enabled.
notifications.dockBadge	true	Count tabs that need you on the Dock icon

About

Key	Default	What it does
updates.checkDaily	true	Check for updates once a day, at launch. Releases come from GitHub, through your own gh.

The About section also shows the version, the commit it was built from, the day it was built, and what the installed build changed.

A worked example

A settings.json with four things changed:

{
  // Keep more scrollback than the default.
  "general.scrollbackLines": 5000,

  "appearance.theme": "Catppuccin Mocha",
  "editor.vimMode": true,
  "browser.agentControl": false
}

That is a complete, valid file: the comment is fine, the trailing comma is fine, and everything not listed stays at its default.

Keyboard Shortcuts

The ninth section is the key map, and it writes keybindings.json rather than settings.json. See Keyboard shortcuts for the defaults and keybindings.json for the format.