Files on disk

Overterm keeps its state in one directory and a handful of preference keys. Nothing is written outside your home folder, and nothing is sent anywhere — see Privacy.

The bundle identifier, which you need for defaults, is io.github.overcraft-hq.overterm.

Application Support

Everything here lives in ~/Library/Application Support/Overterm/:

File	What it holds	Written when
session.json	Tabs — folder, name, colour, pin, agent, splits and their ratios — the islands, and the selection	one second after a change, and on quit
scrollback/<uuid>.txt	A shell pane’s last lines, plain text, named from session.json	once, at quit or when the window closes
snippets.json	Your snippets	when you add, edit or delete one
history.json	Up to 2000 commands with folder, exit code, duration, last run and count	two seconds after a command finishes
settings.json	Only the settings you changed, as JSON5	when you change one in Settings
keybindings.json	Only the key bindings you changed	when you change one in Settings
ghostty-overrides.conf	The Ghostty options and unbinds your settings imply, loaded after your own Ghostty config	whenever those settings change; removed when there are none
mcp/<tab id>.json	One MCP config per terminal pane, mode 0600, holding the server’s port and bearer token	while the browser’s agent control is on; the directory is emptied at launch and a pane’s file deleted with its tab

A file that cannot be read is set aside rather than overwritten, so a corrupted snippets.json or history.json is never silently replaced.

Caches

Path	What it holds
~/Library/Caches/io.github.overcraft-hq.overterm/Drops/<uuid>/	Files dropped on a terminal as promises — from Photos, Safari, the screenshot thumbnail — a folder per drop. In the caches, where macOS may clear them in time.

Preferences

In UserDefaults under the bundle id, because they are window state rather than settings:

Key	What it holds
sidebarVisible	whether the sidebar is open
diffVisible	whether the changes pane is open
sidebarPanel	which sidebar panel — Files, Overgit, Sessions, Snippets
diffScope	Uncommitted or Branch
overgitSections	which Overgit sections are open
openWithApp	the bundle id of the app files open in
NSSplitView Subview Frames OvertermColumns.v5	the column divider positions

The divider key carries a version. It is bumped whenever a column’s width would mean something new, so a stale layout is never applied to a window that has changed shape.

What the agents’ own files are, and are not

Overterm reads several files it never writes:

Path	Read for
~/.config/ghostty/config	your terminal configuration — loaded, never edited
~/.config/ghostty/themes	your own themes, shown in the gallery marked Yours
~/.claude.json	Claude’s quota windows (Usage)
~/.claude/projects/**/*.jsonl	the Sessions panel, “why this file changed”, and the token count
~/.codex/sessions/**/rollout-*.jsonl	Codex’s quota windows and token count
$HISTFILE, ~/.zsh_history, ~/.bash_history	the one-time seed of the command palette’s history

Your Ghostty config is loaded and never written to. Overterm’s own Ghostty options go in ghostty-overrides.conf above, which is loaded after yours.

Agent tabs resume rather than restore

With Reopen the last session’s tabs on, a shell pane comes back with its last 2000 lines of text, replayed from scrollback/. An agent tab does not: its text is not saved, and instead the agent is resumed — claude --continue, codex resume --last — so you get the conversation back rather than a picture of it.

The scrollback replay runs through a small launcher script in the temporary directory, named after your shell so Ghostty picks the right shell integration; it prints the saved text, deletes it, and then becomes your real shell with its integration environment intact. zsh and fish only — bash’s integration goes through its arguments and cannot be wrapped this way.

The final save happens once, at whichever comes first of the window closing and the app quitting: after the window closes its terminals are gone, and a later save would write nothing.

Resetting things

To reset	Do this
tabs	delete ~/Library/Application Support/Overterm/session.json
snippets	delete …/Overterm/snippets.json — the list starts empty
command history	delete …/Overterm/history.json — it seeds from your shell history again
settings	delete …/Overterm/settings.json
key bindings	delete …/Overterm/keybindings.json, or use Settings ▸ Keyboard Shortcuts’ reset
divider positions	defaults delete io.github.overcraft-hq.overterm "NSSplitView Subview Frames OvertermColumns.v5"
which panels are open	defaults delete io.github.overcraft-hq.overterm sidebarVisible (and diffVisible, sidebarPanel, overgitSections)
the app files open in	defaults delete io.github.overcraft-hq.overterm openWithApp — it asks again next time

Renames

Overterm was called Terminus until October 2026. On first launch it moves ~/Library/Application Support/Terminus to Overterm — once, and only when nothing of its own is there yet — so the session, the snippets, the settings and the history come with the name. Settings that predate settings.json (before version 1.17) lived in UserDefaults and are carried over the same way.