The menu bar app
mattstack.app is the macOS menu bar app that rt ships inside. It registers the daemon with launchd, shows its health at a glance, and delivers native notifications, so you don't need a terminal open to know something happened.
The dot
| Dot | Meaning |
|---|---|
| Green | daemon running normally |
| Yellow | daemon starting |
| Orange | pending notifications, or a runaway process detected |
| Pink | daemon reachable but reporting a health problem |
| Red | daemon not reachable |
| Grey | state unknown (before the first status poll) |
Menu actions
From the menu bar menu you can:
- open the mattstack window (Ctrl-Opt-Cmd-M)
- open Processes… or Worktrees…
- open Settings…, open the checklist with Setup status…, or pick up an unfinished setup with Resume setup…
- under Troubleshoot, restart the daemon, view its logs, or open the crash log
- toggle Start at Login
- check for updates
- uninstall mattstack
- quit
The daemon's status line sits near the top. When the daemon is degraded, that line names the cause, for example Daemon: degraded (refresh: 1 enrich error). A crash loop, a failed boot or the last crash reason shows on its own line underneath. To stop the daemon, run rt daemon stop.
Worktrees panel
Worktrees… lists the worktrees that were not cleaned up after their merge request merged or closed. The menu item shows how many there are, and once a day (from 09:00 local, when at least one tree needs a decision) a summary notification opens the panel when clicked.
Each row says why the tree is stuck and whether its work is safe somewhere else: already in the default branch, pushed to the remote, or patch-identical to what merged. It offers one guarded action: dispose, keep, push the branch, review the diff, stop the processes holding the tree, or remove it. Every action re-checks the tree before it runs. A removed tree goes to rt's 14-day trash rather than being deleted, and a tree holding the only copy of its work can only be forced after you confirm.
rt worktree triage prints the same rows in the terminal (--json for scripts). Files that match the rt.worktrees.junk globs, and bun.lock changes that only bump versions, do not count as dirty.
Pane focus
When rt pane focus targets a pane, the app activates the terminal window hosting it. This works for both regular panes and daemon-hosted background panes.
Window behavior
The app stays a regular Dock app for its entire run, so the Dock icon keeps its running indicator. Cmd-W closes the window (and cmd-M minimizes it). Quitting the app when no window is on screen is a real quit, whether from the Dock, Activity Monitor, or a script.
The app catalog is fetched at launch rather than on first window open. This means the first handoff or browser click opens the window without a catalog-fetch delay. The window holds its splash until deck answers and the app list has loaded, up to 90 seconds; a spinner appears beside the logo if that takes longer than the animation. If deck still has not answered, the splash shows "Can't reach deck" with the reason and a Retry button. A tab whose app answers with a server error shows the same kind of failure overlay, with Retry.
Cmd-F opens find in page inside the mattstack window.
While the window is in front, the mattstack app menu holds About mattstack, Check for Updates…, Settings… (Cmd-,), Setup status… and Quit mattstack (Cmd-Q). The Help menu opens these docs with mattstack Help, and has the same View Logs… and Open Crash Log items as the menu bar menu's Troubleshoot submenu.
Settings opens as a native tabbed window (General, Permissions, Fast Browser, Team, Uninstall); the titlebar names the active pane. The General tab's Developer section opens the other app (mattstack.app or mattstack-dev.app) after a confirmation; an app opened by hand takes the Mac over, so it retires and quits the current one.
Updates
mattstack.app updates itself through Sparkle, which verifies the release signature, stages the install, and relaunches the app. It checks every 6 hours and downloads a new release on its own. When a release is ready, the menu item changes to Update Available: <version>; the update installs right away when none of the app's windows are open and setup isn't running, and otherwise when you quit the app.
An update never re-runs Install. Instead, the first launch on a new version runs rt setup update once setup has been finished on this Mac: it runs any one-time migrations the release carries, re-applies the setup steps that are safe to repeat (PATH, settings, skills, intercepts, plugins, Claude permissions, Fast Browser, herdr and the browser extension), then runs the setup check. It never asks you anything and never replaces a value you chose. When the check finds something only you can fix, you get a notification that opens the Setup status window.
Check for Updates… checks on demand. The dev build (mattstack-dev.app) runs from source and never updates through Sparkle.
See also: the daemon guide for what the daemon itself does, and rt daemon in the command reference.