agterm
A native macOS terminal that organizes sessions into named workspaces and exposes a full control API plus agtermctl, letting scripts and coding agents drive every session precisely.
Evidence shows dependencies pinned by revision and built from upstream source (GHOSTTY_REV/ZMX_REV in scripts/setup.sh), with CI pinning and verifying the exact Release entitlement set and checking that nested helpers carry no app entitlements — real least-privilege machinery, so least_privilege and dependency_security score well. The Attribution section carefully delimits libghostty, the macterm-derived bridge files, and original code, earning full marks for source_attribution. However, the control channel is a local unix socket with no stated authentication, authorization, or access control: any local process could create sessions, inject keystrokes, and read back terminal buffers; user confirmation appears only as optional ask/pick prompts, so user_confirmation is deducted. Sensitive-data handling and socket peer permissions are entirely unaddressed. restore-denylist.conf and the restore exclusions constrain auto-rerun commands and provide fallback, but the denylist file itself is not in evidence, so rollback is mid-range.
README, CI, and lint configs are mutually consistent: CI reads pinned revisions from setup.sh and caches them; tests, lint, and cookbook checks all run in CI, supporting self_consistency; pinned dependencies plus a reproducible build support dependency_availability. The README honestly acknowledges the race between session type and session text and that pick/ask block; docs/troubleshooting.md is referenced but its content is not in evidence, so the quality of failure messages cannot be verified and failure_messages stays mid-range.
Audience and scenarios are clearly stated: developers running multiple coding agents on macOS while retaining everyday terminal use; the explicit 'deliberately minimal' boundary statement says what it will not do, so capability_boundaries earns full marks; environment fit is explicit (macOS 14+, arm64 only). Command reference and docs live on agterm.com outside the evidence, so trigger_precision is judged only from README examples and scored mid-range.
Documentation structure is excellent: a layered README pointing to docs, command reference, cookbook, CONTRIBUTING, ARCHITECTURE, and troubleshooting; install notes cover Homebrew, DMG, CLI installation, skill and hook installation, and warn against double-installing; the cookbook has CI-enforced directory/index consistency and fixed headings, so information_architecture, install_notes, examples_and_faq, known_limitations (three restore exclusions, what the reconstructed screen does not retain), and license (MIT with LICENSE file) are well earned. But no CHANGELOG or version file appears in evidence, so versioning_changelog drops to 1; maintenance responsibility is only an Issues/Discussions pointer plus clear disclaimers for third-party ecosystem projects, and naming_stability lacks long-term commitment evidence.
Output usability is evidenced: tree -- dumps the whole model, ask returns the chosen button, session text reads back by line, overlays return exit status; marginal_value is strong — per-session agent status glyphs and scriptable layout are a clear differentiator over ordinary terminals. But the CLI is one command per invocation with no streaming, so agent loops must poll repeatedly, keeping cost_benefit mid-range.
The README separates fact from motivation well, and the restore mechanism's boundary conditions are written concretely rather than as marketing, earning full marks for fact_inference_separation; many verifiable claims point outside the repository (agterm.com, screenshots, the denylist file), so static evidence traces only partially and claim_traceability is deducted; the CI file corroborates README claims about skill files, entitlement sets, and pinned dependencies, but with no actual source files present, corroboration remains partial.
- The control socket declares no authentication or access control: any local process may inject keystrokes and read back terminal content; avoid sessions with sensitive material on shared machines.
- A documented race exists between session type and session text; scripted agents must handle polling and synchronization themselves.
- The skill installs via two routes (plugin marketplace and Help menu); the repo warns double installation is undefined — pick exactly one.
- Live restore depends on zmx and zsh as login shell; the reconstructed screen does not retain inline images, prompt markers, or hyperlink metadata.
- Static review saw no CHANGELOG and no control-server source; socket security and versioning policy remain unverified.
What does this agent do, and when should you use it?
agterm is a native macOS terminal for Apple Silicon Macs with a deliberately small interface and one core model: a window holds named workspaces, and each workspace holds named sessions. Its bundled agtermctl CLI drives nearly everything over a local Unix socket — creating sessions, typing into them, reading pane text back, running programs in overlays, setting status glyphs, and moving windows. Real terminal work (rendering, VT parsing, shell I/O) is handled by Ghostty's embedded libghostty engine; the model, sidebar, persistence, and control channel are agterm's own code. For running several coding agents at once, each agent works in a named session and reports active, blocked, or completed status onto its sidebar row, making it obvious which one needs attention. An installable Agent Skill teaches Claude Code or Codex the control model so an agent can build its own layout, run overlays, and show images inline — not a special agent mode, but the same control surface any script uses.
agterm groups shell sessions under named workspaces, supporting horizontal and vertical splits, scratch terminals, and full or floating overlays that run programs like yazi or a git UI without disturbing the shell underneath. The agtermctl tool provides a complete control surface over a local socket: agtermctl workspace new demo creates a workspace, agtermctl session new --workspace "$ws" --cwd "$PWD" creates a session, session split on --axis horizontal splits it, session type $'pwd\n' --target "$sid" injects keystrokes, session text --lines 10 reads the terminal buffer back, session status blocked sets the sidebar glyph, pick and ask open the native picker and dialogs, and tree -- dumps the entire model as JSON. Three restore modes exist: restore saved layouts with fresh shells, re-run commands captured at quit, or keep actual processes alive with zmx (requires zsh as the login shell). Agent status hooks (installed from the Help menu) let Claude Code, Codex, Pi, OpenCode and other agents report state onto their session rows; a single command line in keymap.conf binds any shell command to a key chord.
- Developers running multiple coding agents in parallel: each agent occupies a named session and reports its status, so it is immediately obvious which one is blocked or done without flipping through tabs.
- Engineers working with Claude Code or Codex: after installing the Agent Skill, the agent can create workspaces, split sessions, run overlay programs, and display images inline without you explaining the API.
- Automation enthusiasts who want a scriptable terminal: use agtermctl to script layout setup, drive sessions you are not looking at, read output back, and react to exit statuses.
- Everyday multi-project users: organize sessions under work/personal workspaces and restore layouts — or keep processes alive — after quitting via one of three restore modes.
- Keyboard-centric customizers: one command line in keymap.conf binds a file manager or database browser to a key chord as a floating overlay.
What are this agent's strengths and limitations?
- Full local-socket control API: scripts and agents can create sessions, inject input, read terminal buffers, and query state — programmability most terminals lack.
- Purpose-built for parallel agent work: active/blocked/completed status appears directly on sidebar rows, with ready-made hooks for Claude Code, Codex, Pi, and OpenCode.
- Embeds the mature libghostty engine for rendering and VT parsing while keeping a minimal feature surface — no deep agent integration, extension is left to the user and scripts.
- Three restore modes, including zmx-based live process keep-alive, so sessions survive restarts and reattach normally.
- Strict platform binding: Apple Silicon Macs on macOS 14+ only; Linux and Windows depend on third-party ports or independent reimaginings.
- Live session restore requires zsh as the macOS login shell, takes effect only after restarting agterm, and hard power loss or force quit defeats command capture.
- Restore has documented limits: inline images, OSC 133 prompt markers, program-changed palette entries, and hyperlink metadata are not retained after reattach.
- Extension is DIY: anything beyond defaults requires writing keymap.conf command lines or scripts — a real cost for users who do not want to customize.
How do you install or deploy this agent?
agterm supports Apple Silicon (arm64) Macs on macOS 14 or later; releases are Developer ID signed and notarized. Homebrew: brew install --cask umputun/apps/agterm (the cask also installs agtermctl). Alternatively download the .dmg from GitHub Releases, drag agterm.app into /Applications, and install agtermctl via Help ▸ Install Command Line Tool…. The Agent Skill installs either from Help ▸ Install Agent Skill… or as a plugin (never both): claude plugin marketplace add umputun/agterm && claude plugin install agterm@agterm, or codex plugin marketplace add umputun/agterm && codex plugin add agterm@agterm. Agent status hooks install from Help ▸ Install Agent Status Hooks….
How do you use this agent?
Launch agterm; sessions are organized by named workspace and reachable by name, recency, or keyboard. A typical scripted flow: ws=$(agtermctl workspace new demo); sid=$(agtermctl session new --workspace "$ws" --cwd "$PWD" --no-select); agtermctl session split on --axis horizontal --target "$sid"; agtermctl session type $'pwd\n' --target "$sid"; agtermctl session text --target "$sid" --lines 10 (note that session type returns once keystrokes are queued, so a following read races the shell); agtermctl session status blocked --target "$sid"; agtermctl tree -- for full state. Customize via command lines in keymap.conf; choose restore policy in Settings ▸ General ▸ Restore sessions or read/write it with agtermctl restore mode. The complete command reference is at agterm.com/commands.
How does this agent compare with similar options?
The README explicitly contrasts agterm with tabbed terminals, which lose track of many long-lived agent sessions, and lists ecosystem relatives: melonamin/agterm-linux is a GTK4 Linux port built on the shared agtermCore, jokius/rook is a native macOS fork taking a different direction, and yeroo/agwinterm is an independent Windows reimplementation. agterm's differentiator is refusing feature bloat in favor of a complete control API that lets users and agents build the rest themselves.
FAQ
Does it support Intel Macs or Linux/Windows?
Is agent status and the skill a special agent-only mode?
What are the prerequisites and limits of Live session restore?
Is it free, and what is the license?
Is output streamed? How do scripts read a session's content?
agtermctl session text --lines N. Also note session type returns once keystrokes are queued, so a following read races the shell.