All pages

Docs · AI features

Pane manifests, flags, and the trmnly CLI

Availability: macOS. The surface_* tools resolve through NSApp.windows, so they are withheld from non-macOS hosts — see Platforms. The trmnly command itself ships on Linux, against a smaller tool surface — see The CLI on Linux.

Every terminal pane can say who it is and what it is doing. That state renders in the sidebar, streams to a log any process can tail, and is reachable from a one-line shell command — so a Claude Code session, a Codex run, a Makefile, or a cron job can all use it without being an MCP client.

Why

Run six agents in six panes and the sidebar shows you six shells. Which one is planning, which is mid-migration, which stopped twenty minutes ago waiting for a decision you never saw? Manifests answer that from inside the pane.

The trmnly command

Every pane exports $TRMNLY_SURFACE_ID, so commands default to the pane you are in. The binary lives inside the app bundle; if TRMNLY's own directory is on your $PATH it already works. Check with trmnly identify, and install a symlink from Settings → AI Agent → Pane manifests if not.

trmnly set-title "F2 Routes"
trmnly set-description "Implementing the route table; next, smoke tests."
trmnly set-status running
trmnly set-progress 0.4
trmnly set-agent --type claude-code --model claude-opus-5

The sidebar row for that pane now reads F2 Routes, with a model chip, a status pill, a progress bar, and the description as its subtitle.

Title and description

  • Title is stable identity: 2–3 words, role first. Make the first word differ between sibling panes — the sidebar truncates from the right, so leading characters are all that survive. F2 Routes, P2 SPA Plan.
  • Description is the live subtitle. Present tense, what you are doing now and the next gate: "Auditing retry admission against the shipped tests; next, verify cancellation." Refresh it at transitions, not on a timer.

Status decays; description does not

status expires after five minutes. Past that the pill shows TRMNLY's own inferred activity instead, marked with a ~ so you can tell an inference from an assertion. This stops a dead agent's last words from being presented as current.

The description never decays, which is exactly why keeping it fresh is the agent's job: a stale subtitle is a lie the operator cannot detect.

progress decays on the same five-minute clock: a bar nobody has updated in that long disappears rather than claiming 40% forever. It takes 0–1; a whole number from 2 to 100, or 45%, is read as a percentage.

Arbitrary keys

Canonical keys (title, description, role, status, task, model, agent, progress) are type-checked and rendered. Everything else is stored verbatim and ignored by the UI — that open key space is for orchestrators coordinating across panes.

trmnly set-metadata --key lane --value migration --type string
trmnly set-metadata --json '{"shards":10,"owner":"orchestrator-3"}'
trmnly get-metadata --json

The blob is capped at 64 KiB per pane. Put large payloads somewhere else and store a reference.

Flags: asking for the operator

trmnly raise-flag "Need a call on schema migration vs dual-write"

The pane turns violet in the sidebar, sorts to the front of the attention queue, and fires a notification even when TRMNLY isn't frontmost. The reason is required and shown verbatim — write the sentence you would say if the operator walked over.

Typing into a flagged pane lowers its flag. The first keystroke of a reply is the answer arriving.

Use a flag only when you have stopped on a decision a human has to make, or hit something urgent whose blast radius reaches other panes. "I finished, please review" is not a flag. Most agents should never raise one; the tier's power is its scarcity.

trmnly flags          # every flagged pane, oldest first
trmnly lower-flag

Suppression: keeping a fleet quiet

trmnly suppress       # and `unsuppress`

Withholds a pane's routine signals — idle and completion styling, the waiting count. Flags still escalate at full strength.

Suppress only when you know another agent owns this pane's outcomes: it launched the worker, consumes its completion, handles its recoverable blockers. That knowledge comes from the launch relationship, never from a guess. A parent that suppresses a worker takes on both channels and should put this in the worker's prompt:

Report completion and recoverable blockers to your parent. Raise a flag only when operator action is required.

Orientation

trmnly tree           # every window, pane, and manifest; --json to script it
trmnly identify       # this pane's ids and paths

tree crosses windows, unlike list_panes, which stays inside the current tab. It is the call to make before reshaping the window layout, or when answering "is anything waiting on me?".

The event log

Everything structural appends one JSON line to ~/Library/Application Support/TRMNLY/events/events-<instance>.ndjson: surfaces opening and closing, focus moves, manifest writes, flags, liveness flips, and commands finishing with their exit codes.

trmnly events tail -f
trmnly events tail --filter flag.raised --since 30m
trmnly events tail --since 1200 --json
trmnly events instances

The file is the contract. trmnly events tail is sugar over reading it, and it works with TRMNLY closed — which is what makes it useful after a crash. Any process that can tail -f is a first-class consumer.

Order by seq, never by ts: seq is assigned on the writer's serial queue, so file order and sequence order always agree, while ts is captured on the emitting thread and can invert slightly under load. seq is monotonic within one instance and resets for each run of the app.

The log rotates at 8 MB, keeping one previous generation, and the five most recent instance logs are retained. progress writes are deliberately excluded — a bar ticking a hundred times is one story, not a hundred events.

Anything else

trmnly tools --grep browser     # every tool the app exposes
trmnly call surface_list '{"flagged_only":true}'
trmnly send "npm test" --submit
trmnly read-screen --full
trmnly split right
trmnly notify "build green" --title CI

call reaches any of TRMNLY's tools, so the CLI is never the limiting factor.

Targeting another pane

Surface commands default to $TRMNLY_SURFACE_ID. To target a different pane, pass --surface <uuid> (get them from trmnly tree).

If neither resolves — a cron job or a hook running outside any pane — the command fails rather than falling back to whichever pane is focused. Silently retargeting another agent's manifest is near-impossible to debug from either side, so it is refused loudly instead.

Inside tmux

Every shell in a tmux session inherits the environment of whichever pane started the server, so $TRMNLY_SURFACE_ID there names the pane tmux was launched from — which may be one you closed an hour ago. trmnly does not trust it: under tmux it asks which client is attached and uses the pane that client is running in.

trmnly identify shows the pane it settled on, and trmnly doctor prints a tmux line with the chain it followed to get there. With the session detached, or attached from a terminal that isn't TRMNLY, no pane resolves and the command fails rather than writing to a stale one.

From the agent side

The same surface is available as tools: surface_set_title, surface_set_description, surface_set_status, surface_set_progress, surface_set_agent, surface_set_metadata, surface_get_metadata, surface_clear_metadata, surface_raise_flag, surface_lower_flag, surface_suppress, surface_unsuppress, surface_list, and events_tail.

The CLI calls exactly these, so validation and behavior are identical whichever way you reach them.

The pane mesh

A pane can also start and drive other panes, so one terminal comes to run several:

  • pane_spawn starts a child pane linked to the one that spawned it, optionally running a command first (the pane then drops to a shell) and giving it a name that works as a target.
  • pane_send puts a message in another pane's inbox; pane_recv reads one.
  • pane_type types keystrokes into another pane's terminal (submit presses Enter) — a controller driving a worker.
  • pane_title reads or sets a pane's title from another pane, across windows.
  • pane_tree shows every live pane with its handle, parent, title and inbox depth.

Targets are a surface UUID, a name, or parent, children or all.

The CLI on Linux

The trmnly binary is built from the same sources on Linux, and the GTK app serves a tool surface for it: a Unix socket under $XDG_RUNTIME_DIR/trmnly/, named by the app's process id so two TRMNLYs on one login session don't collide, speaking the same newline-delimited JSON-RPC as the macOS bridge.

Every pane exports $TRMNLY_SURFACE_ID, $TRMNLY_SHELL_INTEGRATION=1 and $TRMNLY_BIN. Where the app is serving the socket it also exports $TRMNLY_SOCKET_PATH and $TRMNLY_SOCKET_TOKEN. Those two are absent rather than empty when there is no tool surface — the core isn't installed, or the host doesn't serve one at all, as on Windows today. Absence is the answer: a path with nothing behind it would leave a script unable to tell "no surface here" from "the app is wedged".

What that surface serves is the portable core's tool set — files, grep, bash, git, worktrees, notes, the board, chat, review notes, ports, LSP, access keys, GitHub — reachable with trmnly call <tool>. A tool this host can't run is left out of its list entirely, and calling it anyway comes back with the platform reason rather than a generic failure, so a script can tell a gap from a typo.

The manifest itself is not in that set. set-title, set-status, the flag commands and tree all go through surface_*, which resolves panes through the macOS app's windows, and events reads the event log only the macOS app writes. Those are macOS commands, and off macOS they say so.

Two smaller differences worth knowing:

  • trmnly --version reports the portable core's version, not an app version. Off macOS there is no bundle to read one from, and trmnly ? (?) in a bug report reads as a broken install rather than as a different host.
  • Run outside any pane — a cron job, a git hook, an ssh session — trmnly looks for a socket that is being served, not merely a file left behind by an app that crashed. With two apps running it takes the most recently started. The core also stops itself when the app that spawned it goes away, so a crash doesn't leave a socket nobody owns.

Settings

Settings → AI Agent → Pane manifests controls whether the chips render and whether the event log is written, and installs the CLI symlink. Turning the chips off hides the UI only — panes keep writing manifests, because the data serves external consumers as much as the sidebar.