agterm plugin

---
name: agterm
description: >
  Drive agterm, a macOS terminal, via agtermctl. Use in an agterm session:
  manage sessions, companions and workspaces; split panes; toggle the scratch; run, hide or show overlays;
  read exit status; show HTML pages, URLs or dev servers in an overlay with saved logins or as a
  page row;
  post a HUD/caption/notification/sidebar activity line; message panes; show a picker, question or input dialog; show images/markdown/code; type
  into or restart a pane by id, copy its selection, set the clipboard, search its scrollback; manage windows, font size and
  theme; reload or edit the keymap, event hooks and agterm-scoped ghostty config; run a custom command; read
  a closed window's session screen; subscribe to status, notify, lifecycle, selection,
  pane, tree and launch events; wait on agent status.
  Covers window/workspace/session addressing, session links, AGTERM_* variables,
  attaching another Mac's sessions, agterm-server windows, cookbook recipes, version and upgrades, diagnosing
  problems, filing a bug or feature request.
when_to_use: >
  Trigger on: agterm, agtermctl, AGTERM_SESSION_ID, and, from inside a session, plain requests such as
  split the pane, print a link that jumps to a session, close the overlay, hide the overlay for a moment, show a message over the session, show a question dialog, agtermctl ask,
  ask the user to type a value or a message, let the user pick one or several items from a list,
  show an image inline, show this markdown file rendered, show this source file or log at a line, show me the diff of a file or the changes as links, tail or follow this log file, search the log or text page in the overlay, wrap long lines in the text or log page, show this HTML page or artifact, make an HTML page or explainer for this and show
  it, make a page that switches sessions or returns a choice, preview the report you generated, show this URL or the running dev server, keep me logged in to a page shown in an overlay, search the scrollback, flag every session in a workspace, tint a session or workspace row a color, show status or activity under a session in the sidebar, make a companion session, keep a related program next to a session, duplicate this session with its programs as a companion, make this session a companion, open a sub-session under this one, fold a session's companions, show a page as a companion of this session, open a page as its own session row in the sidebar, run my custom command, send a message to the other pane or another agent, read my messages, wait for a message, tell me when the selected session changes, wait until that worker session finishes, bring back the session I just closed, attach a session from another Mac, attach a remote session with all its companions, open a remote window for my Linux server, run sessions on a Linux host with agterm-server, install agterm-server on a Linux host, detach or reattach a remote session, copy this to the clipboard, was agterm upgraded under the running app, upgrade agterm without losing sessions, what recipes are there,
  the keymap editor will not open.
allowed-tools: Bash(agtermctl *)
---

<!-- agterm-skill -->

# Driving agterm

agterm is a native macOS terminal. It exposes a programmatic control channel over a local unix
socket, driven by the companion CLI `agtermctl`. Use it to build and steer terminal layouts, run
programs in overlays, type into sessions, notify the user in the exact session you are working in,
and subscribe to control events. Events cover status, notifications, session lifecycle, split and
scratch pane visibility, structural tree changes (an overlay, page or HUD opening or closing included)
and the app's launch; `hooks.conf` runs a shell line on any of them, so `on app.launched` is where a
script recreates what a relaunch does not restore. They do not stream terminal output; use `session text` to read a buffer.

## Am I inside agterm?

Each shell agterm spawns gets these environment variables. Check `AGTERM_ENABLED` before assuming
the control channel is available:

- `AGTERM_ENABLED=1` — this shell runs inside agterm.
- `AGTERM_SESSION_ID` — the current session's UUID (the session this shell belongs to).
- `AGTERM_WINDOW_ID` / `AGTERM_WORKSPACE_ID` — the owning window / workspace UUIDs. The workspace id is