All pages

Docs · Other surfaces

Tab Monitor

Availability: macOS.

A tab-monitor rule pairs a trigger with an action: notify you when a build fails, ping the agent when a watched file changes, or flag activity after a git commit lands.

Tab-monitor rules live in the Flows sidebar under Tab-monitor rules (they used to be a standalone tab). Create one with Open editor… there, or in Settings → Notifications. See Workflows (Flows) for the surrounding surface — run logs, tags, and import/export.

Triggers

Trigger Fires
Line match (default) When a command finishes in any pane and its new output contains a matching line. Scans happen at command boundaries (shell integration), so output streaming from a still-running command — a dev server, a tailed log — isn't matched until that command exits; point the watch_terminal agent tool at those. A rule fires at most once per command, with a short cooldown against rapid re-runs. The editor's live preview shows which sample lines match, and Test fire in the Flows row menu runs the action on demand.
Cron interval Every N seconds. The engine ticks every 30 s, so shorter intervals round up.
File change When any watched path (file or directory) changes.
Tab idle After N seconds without activity (at most once per interval).
Git commit After a commit lands in the scoped project's repo. Requires a project scope.

Rule anatomy

Field What it does
Name Display label (optional, helps when you have many)
Pattern What to match in each line
Match Contains (literal substring) or Regex (NSRegularExpression syntax)
Case-insensitive Defaults to on; the editor's aA checkbox makes a rule case-sensitive
Action What to do when the rule fires
Project Scope the rule to one project, or leave it on Any project
Trigger One of the trigger types above
Enabled Toggle without deleting

TRMNLY seeds two example rules on first launch: Build failed and Waiting for input.

Actions

Action Effect
Notify macOS notification titled by the rule, showing the matched line
Bell System beep + the tab lights up in the tab list. Timed and event triggers have no tab to target, so they fall back to a notification.
Send to agent sidebar Send the matched line (or event) to the agent as a message — it responds in the agent sidebar
Mark tab for attention Light up the tab badge without notifying (timed and event triggers fall back to a notification)

Useful patterns

Goal Pattern Match Action
Build done BUILD SUCCEEDED|BUILD FAILED Regex Notify
Test failures ^FAIL Regex Mark tab for attention
Stack trace Traceback (most recent call last) Contains Notify
Watch a log for errors [ERROR] Contains Send to agent sidebar

Patterns that would freeze the app

A rule's regex runs against every line every watched pane prints. Some patterns don't fail on a long line — they take seconds or minutes, and TRMNLY can't interrupt a match once it starts. Three things keep that from freezing the app:

  • Two shapes are refused when you write them, with a note under the pattern saying what to write instead: a group that repeats inside a repeat, like (a+)+ or (\d+\.)+ (write [\d.]+), and two unbounded wildcards side by side, like .*.*. Wildcards with text between them (Error.*in.*line) are fine.
  • Very long lines are matched on their first and last 512 characters. ^… and …$ still see the real start and end; a match only in the middle of a line over 1 KB is missed.
  • A rule that takes over 100 ms on a line twice within a minute is switched off, with the measured cost shown as the reason and a notification. Simplify the pattern and turn the rule back on.

Contains rules can't backtrack, so only the line limit applies to them. The cloud workspace's rules have had the same protection for longer.

Scope and persistence

Rules can be scoped to a project — scoped rows are marked in the Flows list and only fire for that project. Leave a rule unscoped to apply everywhere. Each rule has its own enable toggle, so you can keep a library and turn entries on as needed.

Rules survive relaunch and can be exported/imported per rule from the Flows row menu. The agent can manage them too, via the list_tab_monitor_rules, add_tab_monitor_rule, update_tab_monitor_rule (change any field in place by id or name; a bad regex is refused rather than saved disabled), set_tab_monitor_rule_enabled, and remove_tab_monitor_rule tools.

Tab status badges

Each row in the sidebar's tab list carries small badges for its tab, and they cover every split in the tab, not just the one you're focused on:

Badge Means
Blue dot New output in some split since the tab was focused
Orange triangle A command failed or a rule flagged the tab
Pulsing green dot An agent is working — a CLI like Claude Code, a cooperating program's progress report, or the TRMNLY agent in the focused split
Orange hand An agent CLI is sitting at its prompt, waiting for you
Red circle An agent or progress report signalled an error
Spinner A command has run for 3 s or more (not shown for an editor, pager or ssh session parked at its own prompt)
Red number The last non-zero exit code, from the focused split if it has one

When splits disagree, the most pressing state wins — error, then waiting, then working — and the tooltip names how many other splits are active. The window title's prefix (🟢 / ✋ / 🔴) follows the same roll-up. CPU and memory on the row are the focused split's.

The flag, status chips and progress bar under the title also come from whichever split has something to say: a split that raised a flag first, then one reporting progress (trmnly progress / surface_set_progress), then any split with a status or chips. The focused split wins a tie, and when no split has anything, the row shows the focused one as before. The title itself always stays the focused split's. Agents see the same roll-up as tab_status on each tab from list_all_tabs with include_activity.

An agent CLI stays "working" for a few seconds after it goes quiet, so a pause while it waits on the model doesn't read as waiting for you. TRMNLY also reads the working spinner in the agent's title (Claude Code puts one there), so an agent waiting on a slow model reply or a long tool call — using almost no CPU — still reads as working. A single keystroke at an idle prompt doesn't count as work.

Tabs you aren't looking at refresh their spinner and agent badge about every 6 seconds, and update their title once a second rather than on every change; a hidden tab also gives back its drawing buffers until you return to it. The tab in front is unaffected.

On Linux

The Linux (GTK) app has no sidebar tab list, so its tab bar carries the one signal it can: a spinner in the tab while any split in that tab is reporting progress (OSC 9;4 — set, indeterminate, paused or error). It covers every split, so a build in a background split, or in a tab you aren't looking at, still shows. It stops when the program clears its report, when the report goes stale (15 s without an update, the same timeout as the split's own progress bar), or when that split is closed or moved to another tab. An error report keeps the spinner rather than highlighting the tab — the highlight is the bell's — and the split's progress bar turns red. With progress-style = false there is neither a progress bar nor a spinner.