Giving a coding agent control of Macterm

[thdxg]

Agents can already spawn a subprocess. What they can't normally do is watch a program that draws to a terminal — a REPL, a debugger, a dev server's TUI, an interactive installer. macterm pane dump reads the terminal's own cells, so an agent can act with pane run and see the result with pane dump, whether or not it's running inside Macterm itself.

Drop this in ~/.claude/skills/macterm/SKILL.md and your agent picks it up when the task calls for it.

---
name: macterm
description: Control the Macterm terminal emulator from the command line — run commands in panes, read what a pane is displaying (including full-screen TUIs that produce no pipeable output), create tabs and splits, and manage persistent sessions. Use whenever the user asks to run something in a Macterm pane, inspect what a terminal is showing, drive an interactive program, or set up a workspace layout.
---

# Macterm control CLI

`macterm` drives a running Macterm over a Unix socket. Same-user only.

## Reaching it

- **Inside a Macterm pane**: `macterm` is already on `PATH`, and `$MACTERM_SESSION`
  is that pane's own session — so a bare `macterm pane split` self-targets.
- **Outside**: run `/Applications/Macterm.app/Contents/Resources/bin/macterm`.
  It discovers the socket itself; pass `--socket <path>` only to pin a specific
  install (e.g. a debug build alongside a release one).

Exit codes: `0` success, `1` Macterm reported an error, `2` couldn't reach it.
Nothing goes to stdout unless the command succeeded. Every verb takes `--json`.

## Verbs

| | |
|---|---|
| `pane list` | Panes with session names, cwd, foreground process, focus marker |
| `pane dump [--scrollback]` | What the pane is displaying — the observation channel |
| `pane run <text>` | Type text plus a newline into a live pane's shell or REPL |
| `pane key <chord>` | One encoded keypress: `ctrl+c`, `ctrl+d`, `escape`, `up` |
| `pane split [--direction right\|down] [--run CMD]` | Split a pane |
| `pane focus`, `pane zoom`, `pane close` | Focus, zoom, close |
| `tab list/new/select/close` | Tabs; `tab new --run CMD` spawns a command |
| `grid RxC` | Split into an equal grid (≤16 cells) |
| `session list/info/kill` | The zmx sessions backing panes |
| `layout apply/save` | Reconcile or capture the workspace layout |

## Rules

**Target explicitly.** `--pane pane:2` is the 1-based index within the active
tab. `--session macterm-…` is restart-stable — pane UUIDs regenerate every
launch, session names don't. Read both from `pane list`.

**Wrap redirects in `/bin/sh -c '…'`.** Typed text lands in the *user's* shell,
and shells disagree: in nushell `>` is a comparison operator, so a bare
`echo ok > /tmp/done` silently writes no file.

**Wait for a sentinel, never a sleep.** There is no reliable "is it finished"
signal to poll:

```sh
rm -f /tmp/done
macterm pane run --pane pane:2 "/bin/sh -c 'make test; echo ok > /tmp/done'"
until [ -f /tmp/done ]; do sleep 0.5; done
macterm pane dump --pane pane:2 | tail -20
```

If you poll the screen instead, remember the line you typed is echoed there —
assemble the marker at runtime (`printf done-%s $NONCE`) so the joined string
only ever appears in real output.

**A `busy` error means ask the user, not retry with `--force`.** Forcing a close
kills that pane's session and whatever was running in it. Close verbs always
require an explicit target.

**`pane resize` is debug-only, and its failure is misleading.** A release CLI has
no `resize` subcommand, so it falls through to `pane`'s default (`list`) and
reports `Unexpected argument 'resize'` under a `pane list` usage line — nothing
about the real cause. Use `pane resize-split --axis <horizontal|vertical>
--ratio <0.15–0.85>` instead, which exists in every build.

Project-scoped instead of personal? Same file at .claude/skills/macterm/SKILL.md in the repo.