What is umputun/agterm?

agterm is a native macOS terminal that groups shells into named workspaces and exposes nearly all of its state through a bundled CLI over a local socket. It is aimed at people running several coding agents at once, and it is deliberately narrow.

Can I use umputun/agterm commercially?

Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.

Is umputun/agterm still maintained?

Yes. The repository last received commits 1 day ago.

What programming language is umputun/agterm written in?

Mainly Swift, according to GitHub's language statistics.

agterm review: a macOS terminal with a control API for agent sessions

At a glance

What is it?: agterm is a native macOS terminal that groups shells into named workspaces and exposes nearly all of its state through a bundled CLI over a local socket. It is aimed at people running several coding agents at once, and it is deliberately narrow.
Who is it for?: Adopt agterm if you run several long-lived coding agents on an Apple Silicon Mac and want each one to report active, blocked, or completed onto a visible session row, with a scriptable CLI to drive the layout. Do not adopt it if you are on Intel hardware, on macOS 13 or earlier, or if you need a terminal that ships a plugin ecosystem, because agterm answers most feature requests with bind it yourself in keymap.conf.
Can I use it commercially?: Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?: Yes. The repository last received commits 1 day ago.
What is it written in?: Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.

DEEP OPEN-SOURCE ANALYSIS

Hysen Labs Editorial · September 10, 2026 · umputun/agterm

The problem agterm solves is session tracking, not terminal emulation

A tabbed terminal does not tell you anything about the tab you are not looking at. Run four or five coding agents in parallel and the tab bar becomes a list of names with no state attached. agterm's answer is to make the session a first-class object with a name, a working directory, its own scrollback, and a status glyph that an agent can set. The README states the motivation directly: each agent works in a named session and reports whether it is active, blocked, or done, so it is obvious which one needs you. That is the whole pitch. The audience is developers who keep multiple agent processes alive across projects and want to see at a glance which one is waiting on input. Anyone who opens one shell at a time gets a capable terminal, but not the feature that justifies the project.

Workspaces, sessions, splits, and overlays: the four-level model

The hierarchy is small enough to hold in your head. A window is a top-level bundle of workspaces and sessions with its own macOS window and sidebar tree. A workspace is a named group of sessions for one project or context, such as work or personal. A session is one running shell with a name, a working directory, and its own scrollback, and it keeps running while you work in another one. Below that, a session can split into two shells side by side or top and bottom, both sharing the one sidebar row, and it can open a scratch terminal over itself for a quick aside. An overlay is a single program running in a temporary terminal over a session; it disappears when the program exits and leaves the shell underneath unchanged. That last distinction matters. A split adds a persistent pane to the session, while an overlay borrows the session's screen for one command and gives it back. The README's own example is running yazi, a file manager, in a floating overlay from one command line in keymap.conf.

What agtermctl can actually do over the local socket

The bundled agtermctl is the part worth reading carefully, because it is what separates agterm from a terminal with a config file. According to the README, it creates sessions and 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. Reading a pane's text back and returning an overlay's exit status are the two capabilities that make scripting meaningful: a script can start a command, wait for it, inspect what it printed, and branch on the result rather than guessing from timing. The status glyph is likewise scriptable, so the active, blocked, or completed indicator is not reserved for the bundled agent hooks. Anything that can talk to the socket can set it. The README is explicit that agent integration is not a special mode: it is the same control surface anything else uses.

Install paths: Homebrew cask, DMG, and the Help menu installers

Pre-built releases target Apple Silicon (arm64) Macs running macOS 14 or later, and the README notes they are signed with a Developer ID certificate and notarized by Apple, so Gatekeeper opens them without extra steps. The Homebrew route is one command: brew install --cask umputun/apps/agterm. That cask already installs the agtermctl command-line tool. From the DMG, you download the latest .dmg, open it, drag agterm.app into /Applications, and then put agtermctl on your PATH through Help ▸ Install Command Line Tool. The same Help menu installs the agent status hooks and the agent skill, both described as optional and safe to rerun. The skill is installed from Help ▸ Install Agent Skill and teaches Claude Code or Codex the control model and the agtermctl commands, so an agent running inside agterm can build its own layout, run overlays, manage windows, and show images inline. Status hooks for Claude Code, Codex, Pi, OpenCode, and other agents install from Help ▸ Install Agent Status Hooks.

Three restore modes, and the zsh constraint on live sessions

Restore behaviour is a genuine design decision rather than a checkbox. agterm offers three modes. The first restores the saved layout with fresh shells, which is the safe default and loses whatever was running. The second starts the commands that were captured at quit, which replays your setup but not the process state. The third keeps the actual primary and split processes alive with zmx. That third mode is the interesting one and also the constrained one: the README states that live sessions are global, require zsh as the macOS login shell, and take effect after restarting agterm. Three limitations in one sentence. If your login shell is bash or fish, the live mode is unavailable to you, and switching your login shell to get it is a system-wide change, not a per-app setting. The globality is the other constraint: live sessions are not scoped to a window or workspace, so you cannot opt one project into zmx persistence and leave another on fresh shells.

The deliberate answer to feature requests is to bind it yourself

agterm's minimalism is a stated position, not an accident of an early release. The README says the design covers the listed use cases and stops there, and that anything past the defaults you build yourself instead of waiting for it to ship. The mechanism for that is a command line in keymap.conf, which turns any shell line into a key chord, combined with overlays that give an interactive program a real terminal over the session. The README's framing is that a file manager, a git UI, or a database browser is one line away. This is the trade-off to weigh honestly. You get a small surface and a complete control API, and in exchange there is no plugin registry, no theme marketplace, and no built-in file manager to click. The project's own mitigation is to not write those lines by hand: install the agent skill and ask the agent in your session for what you want, and it writes the line with the right syntax, targeting, and PATH handling. That mitigation depends on you having an agent in the session and trusting it to edit your keymap.

Where agterm is the wrong tool

The platform boundary is hard. Releases are built for Apple Silicon and require macOS 14 or later, so Intel Macs and older macOS versions are out, with no source-build instructions in the supplied material. Beyond that, the terminal engine is not agterm's own: rendering, VT parsing, and shell I/O come from Ghostty's engine, libghostty, and everything above it is agterm's. That is a reasonable split, but it means terminal-emulation bugs and escape-sequence gaps are inherited rather than fixed here, and agterm's own surface is the session model and the control layer. If you want a terminal you can extend with a scripting language inside the process, or one with a long tail of community plugins, agterm is not that and does not intend to be. If you need a cross-platform terminal that behaves the same on Linux and macOS, this is macOS-only. And if your work is a single shell in a single directory, the workspace and session hierarchy is overhead you will not use.

Compared with a multiplexer like tmux

The closest point of comparison for the session model is tmux, and the difference is where the state lives. tmux runs a server, keeps sessions and panes in it, and you attach from any terminal; its scripting surface is the tmux command language and its own key table. agterm is a GUI application with a sidebar, and its scripting surface is a separate binary talking to a local socket. The practical consequences differ in both directions. tmux survives a terminal crash and can be attached to over SSH, which a macOS GUI app with a sidebar does not do. agterm gives the session a visible row in a window, a status glyph an agent can set, a dashboard that shows several sessions' live output in one view-only grid, and a picker, none of which tmux offers without configuration. If your sessions need to outlive your laptop's display or be reachable remotely, tmux is the better fit. If your sessions need to be visible and scriptable on one Mac, agterm's model is more direct.

Maintenance cost, release cadence, and the MIT licence

The repository shows an active cadence: v0.27.0 and v0.27.1 on 2026-09-07, then v0.28.0 on 2026-09-09, with the last push on 2026-09-10. The version numbers are still pre-1.0, which is worth reading as a signal about interface stability rather than as a judgement on quality. The agent skill, the status hooks, and the keymap.conf command lines are the surfaces most likely to move, because they encode assumptions about external agents such as Claude Code and Codex that change on their own schedule. The Help menu installers being safe to rerun is the project's own answer to that drift. agterm is MIT licensed, which permits commercial and private use and modification; the bundled Ghostty engine carries its own licence, so if you redistribute a build, check the terms that come with libghostty rather than assuming MIT covers the whole binary. That is a packaging question for your legal team, not something to settle from a README.

Editorial conclusion

Adopt agterm if you run several long-lived coding agents on an Apple Silicon Mac and want each one to report active, blocked, or completed onto a visible session row, with a scriptable CLI to drive the layout. Do not adopt it if you are on Intel hardware, on macOS 13 or earlier, or if you need a terminal that ships a plugin ecosystem, because agterm answers most feature requests with bind it yourself in keymap.conf. Before committing, verify that your login shell is zsh, since the live zmx restore mode requires it, and confirm that the agent status hooks install cleanly for the specific agent you use.

Official sources

Community notes