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.