umputun/agterm

agterm – a minimal macOS terminal with a full control API

What it is

A native macOS terminal application built on the Ghostty rendering engine. It provides a tiny UI focused on workspaces (named groups of sessions) and a programmable control surface.

Key features

Workspaces & sessions – each workspace holds multiple named shell sessions that keep running even when you switch to another one.
Control API (agtermctl) – a command‑line tool talks to a running agterm over a local Unix socket. Scripts (or AI agents) can create sessions, type into them, split panes, launch overlay programs, read back terminal text, set status icons, show native pickers, and more.
Splits, scratch panes & overlays – split a session horizontally or vertically, open a temporary “scratch” terminal, or run a full‑screen/floating overlay without disturbing the underlying shell.
Restore modes – on restart you can get fresh shells, re‑run the commands that were active, or keep the original processes alive (Live mode) using the zmx daemon.
Agent integration – optional skill plugins teach Claude Code, Codex, or other agents the agtermctl commands, letting an AI agent arrange its own layout, run overlays, and report its state (active, blocked, completed) directly in the sidebar.
Extensibility – key bindings are defined in keymap.conf; any command can be bound to a key chord, turning a single line into a powerful UI action.

How you use it

# create a workspace and a session
ws=$(agtermctl workspace new demo)
sid=$(agtermctl session new --workspace "$ws" --cwd "$PWD" --no-select)

# split the session vertically
agtermctl session split on --axis horizontal --target "$sid"

# type a command into the hidden session
agtermctl session type $'pwd\n' --target "$sid"

# read the last 10 lines of its output
agtermctl session text --target "$sid" --lines 10

The API covers windows, panes, overlays, notifications, pickers, and even JSON dumps of the whole model.

Installation

Distributed as a signed .dmg for Apple‑silicon Macs (macOS 14+).
Also available via Homebrew Cask: brew install --cask umputun/apps/agterm (includes the agtermctl binary).
Optional agent‑skill plugins can be installed through the terminal’s Help menu or via Claude/Codex plugin commands.

Who it’s for

Developers who run many long‑living coding agents or background processes and need a clear visual overview.
Power‑users who like to script their terminal layout and automate window management.
Anyone who wants a lightweight macOS terminal that can be driven programmatically rather than manually.

Related projects

agterm‑linux – a GTK4 port for Linux.
agwinterm – a Windows re‑implementation.
Various companion tools that push agent status to remote tmux sessions, etc.

License – MIT.

All details are taken directly from the repository’s README; no additional features are inferred.