Skip to content
overterm
Documentation

Why a terminal for agents

The problem Overterm exists for — several worktrees, an agent in each, and no way to tell which one stopped.

Running one coding agent needs nothing special. You start it, you watch it, you answer it. Running five is a different job, and it is the job Overterm is built for.

What changes at five

The work splits into worktrees, because two agents editing one checkout undo each other. So you end up with repo, repo-wt-auth, repo-wt-migrations, repo-wt-flaky-test — four checkouts, four branches, four agents.

Each of those agents spends most of its time working and a little of its time stopped. It stops for three different reasons, and they want three different things from you:

  • it finished, and the work needs looking at;
  • it failed, and something is wrong;
  • it is asking permission, and until you answer it does nothing at all.

In a normal terminal all three look identical from the outside: a tab with a title. The information you need — which of the twelve tabs stopped, and why — is only visible if you are already looking at that tab. So you cycle through them, which is the tax, and the cost of the tax is that an agent blocked on a yes/no question sits idle for ten minutes.

What Overterm does about it

Nothing clever. It reads what the terminal already reports and puts it in the window.

Shell integration and the agents themselves emit more than a title. Claude Code sends a desktop-notification sequence when it wants input and a progress sequence while it works; the shell reports when a command ended and with what exit code. A terminal that keeps those per tab can say “working”, “done”, “failed”, “waiting on you” without asking anything of you or of the agent. That is Tabs and attention.

From there the rest follows from the same facts:

  • Tabs of one checkout collect into a named, coloured group, so twelve tabs read as four pieces of work. See Islands.
  • Every agent that is blocked goes in one list, with its question and its numbered choices read off the screen, so you answer four of them from one place. See Agent Inbox.
  • A worktree, a branch and an agent are one keystroke to make and one click to clean up when the branch is merged. See Worktrees and tasks.
  • What each agent changed, and the reason it gave for changing it, is beside the terminal rather than in a separate app. See Changes.

What it is not

It is not an agent, and it does not talk to one over an API. It starts claude or codex by typing the command into a shell, the same way you would, and it reads what those processes write to the screen and to their own files on this Mac. There is no account, no key and no service in the middle. See Privacy.

It is also not a rewritten terminal. The terminal is libghostty, so your ~/.config/ghostty/config applies as it is and the parts you already rely on — rendering, shell integration, keybinds — are Ghostty’s. Everything described in these pages is the window around it.

Getting started installs it.