# umputun/agterm: a macOS terminal built around a control API for coding agents

> agterm is a native macOS terminal that groups shells into named workspaces and exposes almost everything as an object a script or an agent can drive through agtermctl. It is deliberately small, Apple Silicon only, and its live restore mode depends on zsh.

**umputun/agterm** — A genuinely good terminal

- Repository: https://github.com/umputun/agterm
- Website: https://agterm.com
- Stars: 641 · Forks: 85
- Language: Swift
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/umputun-agterm

## The problem agterm solves: too many long-lived shells, no idea which one needs you

The README states the motivation directly: running several coding agents at once means many long-lived sessions, each progressing on its own, and a tabbed terminal loses track of them quickly. That is a narrower problem than "terminals are bad". A tab bar is a flat list; once you have ten shells across three projects, the tab title tells you the working directory and little else. Nothing in a conventional terminal knows that one session is waiting on a permission prompt and another finished twenty minutes ago.

agterm's answer is a hierarchy and a status field. Shells are grouped into named workspaces, each holding the sessions for one project or context, and each session carries a status glyph that an agent can set. The README describes the intended result plainly: each agent works in a named session and reports whether it is active, blocked, or done, so it is obvious which one needs you. The audience is therefore people who already run Claude Code, Codex, Pi, OpenCode or similar tools in parallel, plus anyone who wants a small terminal whose behaviour can be scripted. It is not aimed at someone who opens one shell and types git status.

## Workspaces, splits, overlays: the whole object model in four nouns

The README defines exactly four things, and the smallness of that list is the design. A window is a top-level bundle of workspaces and sessions in its own macOS window, with its own sidebar tree. A workspace is a named group of sessions for one project or context. A session is one running shell with a name, a working directory, and its own scrollback; it keeps running while you work in another one. A split turns a session into two shells side by side or top to bottom that share the one sidebar row, and a scratch terminal opens over a session for a quick aside. An overlay is one program running in a temporary terminal over a session; it disappears when the program exits and leaves the shell underneath unchanged.

The important consequence is that every one of those objects is addressable. The README says everything agterm holds is also an object a script can address, and the bundled agtermctl creates sessions, types into them, reads a pane's text back, runs a program in an overlay and returns its exit status, sets a session's status glyph, opens the native picker, moves windows, and reads all of that state back out over a local socket. So the sidebar is not just a view; it is a projection of state that a script can also write to.

For rendering, VT parsing and shell I/O, agterm embeds Ghostty's engine (libghostty). Everything above that layer is agterm's own code. That split matters when you evaluate it: terminal emulation correctness is inherited, and the differentiating work is the session model and the control surface.

## The control API and agtermctl: scripting the terminal instead of clicking it

The control surface is the reason to look at this project rather than another terminal. agtermctl is bundled, talks over a local socket, and covers a wide slice of the UI: creating sessions, typing into them, reading a pane's text back, running a program in an overlay and reading its exit status, moving and resizing windows, setting a session's status glyph, and posting a notification tied to a specific session. The README's framing is that a script or an agent can set up and drive its own layout, and send you a notification from the session it was working in.

The same surface serves the agent skill and the agent status hooks. There is no separate "agent mode"; the README is explicit that none of it is a special agent mode and that it is the same control surface anything else uses. That is a real architectural decision with a real cost: because the API is general, the agent integration is not tuned to any one agent's quirks, and the README says as much when it states there is no deep agent integration and no attempt to invent a new way of working with agents.

The extension story follows from the same idea. A command line in keymap.conf turns any shell line into a key chord, and an overlay gives an interactive program a real terminal over the session. The README's example is a file manager, a git UI or a database browser being one line away. The README also says you are not meant to write those lines by hand: install the agent skill from Help ▸ Install Agent Skill… and ask the agent in your session for what you want.

## Installing agterm and driving a session with agtermctl

Pre-built releases are for Apple Silicon (arm64) Macs running macOS 14 or later. Releases are signed with a Developer ID certificate and notarized by Apple, so the README says Gatekeeper opens them with no extra steps. The Homebrew route is one command:

```bash
brew install --cask umputun/apps/agterm
```

The Homebrew cask already installs the agtermctl command-line tool. If you install from the .dmg instead, the README says to put agtermctl on your PATH with Help ▸ Install Command Line Tool…, and the same Help menu installs the agent status hooks and the agent skill, both optional and safe to rerun.

Once agtermctl resolves, the first real use is to create a named session and type into it. The README lists session creation and typing as two of the operations the tool performs, so the shape of the workflow is: ask agtermctl for a session, then send it a command. The exact flags are documented at agterm.com/commands rather than in the README, so check that page before scripting. What you should see is a new row in the sidebar workspace you targeted, with the command's output in its scrollback.

Building from source is a different path and is documented in the repository's Makefile. It is not a one-liner: the debug build regenerates the Xcode project from project.yml and depends on a one-time preparation step that builds libghostty and the Ghostty resources.

```bash
make prep
make build
```

make prep runs scripts/setup.sh and is described as one-time and idempotent. make build regenerates agterm.xcodeproj with xcodegen and then runs xcodebuild against the Debug configuration. make run builds and launches; make deploy builds a release and copies agterm.app into ~/Applications. Note that make deploy is not the same as the signed, notarized DMG that make dist VERSION=x.y.z produces.

## Restore modes and the zsh constraint

agterm offers three restore modes, and they differ in how much survives a quit. The first restores the saved layout with fresh shells. The second starts the commands that were captured at quit. The third keeps the actual primary and split processes alive with zmx.

The live option has constraints the README states without hedging. Live sessions are global, they require zsh as the macOS login shell, and they take effect after restarting agterm. If you run fish, bash or nushell as your login shell, the live mode is not available to you as described. Two further details are worth noticing. Live sessions are global rather than per-window, which means the feature does not respect the window boundary that the rest of the object model is built around. And "take effect after restarting agterm" means changing the setting does not retroactively keep the shells you already have; you find out on the next launch.

The other two modes are safer defaults. Restoring the layout with fresh shells is the least surprising. Restoring captured commands re-runs what you had, which is useful for a fixed set of project shells and risky for anything interactive or destructive, since re-running a captured command is not the same as resuming a process. The README does not document rollback for any of the three modes.

## Where agterm is the wrong tool

The minimalism is a stated design choice, not an accident: the README says the design is deliberately minimal, that it covers the use cases above and stops there, and that you get a sensible minimum out of the box plus a complete control API on top, so anything past the defaults you build yourself instead of waiting for it to ship. Read that as a boundary. If you want a terminal that already contains a file manager, a git UI or a database browser, agterm does not. It gives you the mechanism to bind them, and the README points at the cookbook for bigger workflows, but the work is yours.

Platform is the harder limit. The pre-built releases are arm64 only and require macOS 14 or later. There is no documented Intel build, Linux build or Windows build, and the top-level repository layout is Xcode-shaped (agterm/, agtermCore/, agtermTests/, agtermUITests/, project.yml) with a Makefile whose targets call xcodebuild and xcodegen. If your team is not on Apple Silicon Macs, this is not a candidate.

There is also a mismatch risk on the agent side. Status hooks install for Claude Code, Codex, Pi, OpenCode and other agents from the Help menu, but the status feature only pays off if your agent is among those the hooks support and you actually install them. Without hooks and without scripting, agterm is, by its own description, a capable general-purpose terminal for everyday multi-project work, and you would be paying the learning cost of a new session model for a terminal that behaves like a terminal.

## agterm against tmux and against Ghostty

The closest comparison is not another GUI terminal but tmux. tmux also keeps long-lived sessions alive, also has a scriptable command interface, and also has workspaces in the form of sessions and windows. The difference in approach is where the state lives and who can see it. tmux is a terminal multiplexer inside whatever terminal you already use, so its state is text you attach to, and its scripting surface is tmux commands. agterm is the terminal itself: the sidebar, the status glyphs and the window layout are native macOS objects, and the control surface is a local socket driven by agtermctl. tmux survives your terminal crashing and runs over SSH; agterm is a macOS application, and the README does not describe remote attach. If your work happens on remote hosts, tmux is the thing that already solves it.

The other comparison is Ghostty, and it is unusual because agterm embeds Ghostty's engine (libghostty) for rendering, VT parsing and shell I/O. So the two are not competing on emulation quality; they share the layer that decides it. The difference is everything above: Ghostty is a terminal, agterm is a terminal plus a named-session model, a status field an agent can write to, and a control API. If you want a fast native terminal and nothing else, Ghostty is the more direct choice. If the thing you are missing is knowing which of twelve agent sessions is blocked, that is the layer agterm adds.

## Licence, maintenance and the cost of staying current

agterm is MIT licensed. That is permissive: you can use, modify and redistribute it, including in commercial settings, provided the licence text and copyright notice are preserved. This is a description of the licence identifier in the repository, not legal advice; if you plan to redistribute a modified build, read LICENSE and talk to someone qualified.

The repository is not archived, and the last push was on 2026-09-10. Three releases landed in the days before that: v0.27.0 and v0.27.1 on 2026-09-07, and v0.28.0 on 2026-09-09. The version numbers are still in the 0.x range, which is worth weighing if you plan to build scripts against agtermctl: the README points at agterm.com/commands for the reference, and a 0.x project can change that surface between minor releases. The CHANGELOG.md at the repository root is where those changes are recorded, and it is the file to read before upgrading rather than after.

Upgrade cost depends on how you install. The Homebrew cask is a single command to update, and it carries agtermctl with it, so the CLI and the app stay in step. A DMG install means downloading a new .dmg and dragging the app again, and re-running Help ▸ Install Command Line Tool… if the bundled tool changed. Building from source carries the highest cost: make prep is described as one-time and idempotent, but the debug and release targets regenerate the Xcode project from project.yml, so a source build ties you to xcodegen and a working Xcode toolchain. The Help menu's agent status hooks and agent skill are both described as safe to rerun, which suggests they are meant to be refreshed after an upgrade.

## Conclusion

Adopt agterm if you keep many long-lived agent or project shells open on an Apple Silicon Mac and want to script their layout and status instead of clicking through tabs. Skip it if you need Intel support, a Linux or Windows build, or a terminal that ships a file manager, git UI or database browser out of the box; agterm expects you to bind or script those yourself. Before committing, verify three things on your machine: that you are on macOS 14 or later with an arm64 Mac, that zsh is your login shell if you intend to use the zmx live restore mode, and that agtermctl is on your PATH after installing from the DMG. Then open Help and install the agent status hooks for whichever agent you actually run, because the status glyphs are the feature that makes a screen of concurrent sessions readable.

## FAQ

### What is agterm?

agterm is a native macOS terminal with a deliberately small interface and a full control API. Shells are organized into named workspaces, and the bundled agtermctl drives sessions, overlays, windows and status over a local socket.

### How do I install agterm on macOS?

The README gives a Homebrew cask, brew install --cask umputun/apps/agterm, and that cask already installs the agtermctl command-line tool. Alternatively, download the latest .dmg from the releases page, open it and drag agterm.app into /Applications. Pre-built releases are for Apple Silicon Macs running macOS 14 or later.

### Does agterm support live session restore?

Yes, as one of three restore modes: it keeps the actual primary and split processes alive with zmx. The README states that live sessions are global, require zsh as the macOS login shell, and take effect after restarting agterm.

### Which coding agents can report status in agterm?

Status hooks for Claude Code, Codex, Pi, OpenCode and other agents install from Help ▸ Install Agent Status Hooks…. The agent then reports active, blocked or completed onto its session's row.

## Sources

- [License: MIT](https://github.com/umputun/agterm/blob/master/LICENSE)
- [Project website](https://agterm.com)
- [README](https://github.com/umputun/agterm/blob/master/README.md)
- [Releases](https://github.com/umputun/agterm/releases)
- [umputun/agterm on GitHub](https://github.com/umputun/agterm)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/umputun-agterm