Getting started

Overterm is a macOS terminal built for running several coding agents at once. The terminal itself is libghostty, so your existing Ghostty configuration applies unchanged; everything around it — the tab strip, the islands, the Agent Inbox, the changes pane — exists to keep five or ten agent sessions straight.

This page gets it running. Requirements has the exact versions, and Build from source covers compiling it yourself.

Install the app

Download the latest disk image from the releases page, open it, and drag Overterm to Applications.

Open it the first time

The build is signed ad-hoc and is not notarised — notarisation needs a paid Apple Developer membership the project does not have yet. macOS therefore refuses a plain double-click the first time. Open it once the long way and macOS remembers:

1. Right-click (or Control-click) Overterm in Applications.
2. Choose Open.
3. Confirm in the dialog.

On macOS 15 and newer the dialog may not offer Open at all. In that case go to System Settings → Privacy & Security, scroll to the bottom, and choose Open Anyway beside the message about Overterm.

If you would rather not go through the dialog, clearing the quarantine attribute does the same thing:

xattr -dr com.apple.quarantine /Applications/Overterm.app

Run it from the bundle, not from a build directory — a bare binary has no terminfo and no shell integration, and will crash reaching for the notification centre.

Your Ghostty config still applies

If you already use Ghostty, there is nothing to port. Overterm loads ~/.config/ghostty/config exactly as Ghostty does — font, theme, keybinds, the lot — and then layers its own settings on top as an overrides file loaded after yours. So a setting you have made is a setting Overterm keeps, and anything you change in Overterm’s own Settings never edits your file.

If you have never used Ghostty, there is nothing to do: the defaults are Ghostty’s.

What the window is telling you

Four things are worth knowing on the first day.

Tabs carry state, not just titles

Every tab knows what kind of thing it is — agent, server, shell, ssh — and what that thing is doing: working, done, failed, or waiting on you. Claude Code needs no setup for this; it already emits the notification and progress sequences Overterm listens for.

Press ⌥⌘↓ to jump to the next tab that failed or needs you, rather than hunting through the strip. See Tabs and attention.

Islands group a checkout

Tabs belonging to one checkout collect into a coloured group — an island. Collapse one, stash it while it keeps running, or broadcast a line to every tab in it. ⌃⌘1 through ⌃⌘9 switch between them. A new tab never silently joins an island. See Islands.

The Agent Inbox collects the questions

⌘I lists every agent currently waiting on you, with its question and its choices read off the screen, so you can approve or deny without finding the tab first. See Agent Inbox.

The palette finds everything else

⌘K searches command history, snippets, actions, tabs and worktrees in one list. If you forget every other key on this page, this is the one to keep. See Command palette.

Start a task

The flow Overterm is built around is one key: ⇧⌘N.

⇧⌘N  →  name the task
        ↳ Overterm creates a git worktree and a branch
        ↳ opens it in its own island
        ↳ starts the agent you chose

When that branch is merged, Overterm notices and offers to remove the worktree. See Worktrees and tasks.

Where to go next

• Keyboard shortcuts — the whole default map. Every one of them is rebindable.
• Settings — every key in settings.json, its default, and the Ghostty option it maps to.
• Troubleshooting — the first-open warning, gh, the Metal toolchain, and which Xcode builds it.