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_spawnstarts a child pane linked to the one that spawned it, optionally running acommandfirst (the pane then drops to a shell) and giving it anamethat works as a target.pane_sendputs a message in another pane's inbox;pane_recvreads one.pane_typetypes keystrokes into another pane's terminal (submitpresses Enter) — a controller driving a worker.pane_titlereads or sets a pane's title from another pane, across windows.pane_treeshows 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 --versionreports the portable core's version, not an app version. Off macOS there is no bundle to read one from, andtrmnly ? (?)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 —
trmnlylooks 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.