Show caret in the menu bar¶
Audience: anyone on macOS who wants to see at a glance whether a plan is waiting.
caret's menubar app puts a carrot in the macOS menu bar. The carrot colours in while a plan waits for review and is grey otherwise, including when no caret is running. When it changes, it fades from one to the other in under a fifth of a second. It doesn't fade when the app starts. With Reduce motion on in System Settings → Accessibility, it changes at once.
Its menu opens on a card of your review stats (see Read your review stats), then two items:
- Open caret opens the review page.
- Quit closes the app.
The app needs macOS 13 or later. It runs with or without the background service.
Add the app¶
Run caret install at a terminal. On macOS 13 or later, it asks:
Answer Yes to add the app. It opens right away and starts at login. If it crashes, macOS starts it again. If you choose Quit, it stays closed until your next login.
The question's default is Yes. caret install does not ask under --dry-run or
--uninstall.
Keep the app current¶
The app reads caret's port and address from your settings
when caret install runs. After you change either, run caret install again so the app
finds caret.
The app reaches caret only through this Mac's own address (127.0.0.1 or localhost). It
still works with [daemon] host set to all addresses
(0.0.0.0 or ::). With host set to one specific address other than this Mac's own,
caret install warns and does not install or update the app. To use the app, set host
back and run caret install again.
When caret install runs from a script or another tool instead of at a terminal, it
cannot ask. If the app is installed, it updates it; otherwise it leaves the app out. An
update does not reopen an app you quit, so it stays closed until your next login.
An agent host that updates caret on its own leaves
the app at its old version. Run caret install to update it.
Read your review stats¶
The card at the top of the menu shows the version of caret that is running, and four counts over every review you have done on this Mac:
- plans approved: the plans you approved.
- plans rejected: the plan versions you turned down with Reject. A Reject stays counted when the agent later sends another plan. A plan you send back with Request changes is not counted here; the version the agent sends next counts as a revision.
- revisions: every version of a plan after its first.
- comments: the inline comments and the general comment on versions you approved or sent back with Request changes. A Reject sends no comments, so comments drafted on a rejected version don't count, and nor do drafts on a plan still waiting.
The app asks caret for these as you open the menu. When no caret is running, or the
running caret is too old to report stats, each count shows a dash and the version is the
app's own. Run caret install to update an old caret. When caret answers with an error,
the card says caret didn't answer the app (see
Fix an app that misbehaves).
The ^ and a faint tint on the card take the accent of the themes you chose in the review
page's Settings → Appearance: your light theme's in light mode, and your dark theme's
in dark mode. Until you open the review page, the card uses caret's own amber. With
Reduce transparency on in System Settings → Accessibility, the card is solid, and
with Increase contrast on, its edge is drawn stronger.
Where it lives¶
- The app:
~/.local/state/caret/menubar/(under$XDG_STATE_HOME/caretwhen you setXDG_STATE_HOME). - The LaunchAgent, the macOS file that starts the app at login:
~/Library/LaunchAgents/dev.excessive.caret.menubar.plist. - Its error log:
logs/menubar-stderr.login the same state directory (see Find the log files).
Fix an app that misbehaves¶
If the carrot never appears or keeps vanishing, read logs/menubar-stderr.log. It holds
the app's errors and any crash output.
If the card says caret didn't answer the app, a caret is running but refused the app's
request, most often because the app holds an old copy of caret's address or token. Run
caret install again to refresh them.
If the carrot shows but never colours in, the app records each change of its icon in the macOS log. To read the last hour of it:
Remove the app¶
Run caret install and answer No. That removes the app and its LaunchAgent and keeps
the rest of caret.
To remove all of caret, the app included, run caret install --uninstall (see
Remove caret).