Menu bar app
See which session needs attention without switching terminals. Click the native macOS menu bar icon to open a popover with your plan allowances, each session’s context, cache, and handoff, and today’s locally observed token activity. From it you can focus a session in cmux, generate or open a handoff, and start, stop, and restart the daemon.
The prebuilt download includes the app. For a source install, follow Build and run below. Click the gear in the popover’s header to open Settings and change thresholds and notification settings, then restart the daemon to apply them.
The Updates section at the top of Settings checks for a new published
release at launch and daily while the app is running. Automatic checks are on
by default; turn them off there or use Check Now at any time. The toggle
saves immediately without restarting the daemon. When an update is available,
Download Update opens the download page; follow its installation instructions.
Checks do not install anything automatically. Source builds without the packaged
VERSION file show the latest release but cannot compare it to the running build.
The app reads the daemon’s status file every three seconds. It displays the metrics, alert levels, and activity totals the daemon reports; it does not read agent transcripts or compute thresholds. Unavailable metrics stay unavailable.
The status item is icon only, about 37 pt wide, with no title text beside it. It draws as a template image in the menu bar’s own foreground colour, so it stays legible on any wallpaper, and the shape alone carries the level the daemon derived for the worst session:
| Icon | Meaning |
|---|---|
eye |
daemon running, worst session below the warn line, or no sessions |
eye.trianglebadge.exclamationmark |
worst session at or above the warn threshold |
eye.trianglebadge.exclamationmark.fill |
worst session at or above the critical threshold |
eye.slash |
status file stale, daemon stopped or not running, unreadable, or context unknown for some session |
The worst session’s percentage is not in the icon; it is in the tooltip
(Daemon running (last poll 12s ago) · worst session 81%) and in every
session row of the popover.
Build and run
Requires Xcode command line tools with Swift 5.9 or later. The package declares
swift-tools-version:5.9 and targets macOS 13.
yarn workspace @agent-watchdog/menubar build # swift build -c release
yarn workspace @agent-watchdog/menubar test # swift test (MenubarCore and MenubarApplication)
apps/menubar/.build/release/agent-watchdog-menubar # run it from the repo root
To link the app and register its background service alongside the daemon, run these commands from the repository root:
yarn workspace @agent-watchdog/watchdog start link --menubar-bin "$PWD/apps/menubar/.build/release/agent-watchdog-menubar"
yarn workspace @agent-watchdog/watchdog start install --menubar-bin "$PWD/apps/menubar/.build/release/agent-watchdog-menubar"
The app has no dock icon and no bundle; quit it from More in the popover’s
footer. Diagnostics go to
stderr, prefixed agent-watchdog-menubar:.
Status file location
By default the app reads ~/.local/state/agent-watchdog/status.json, the path
the daemon writes. Set AGENT_WATCHDOG_STATUS_FILE=/some/path.json to point it
elsewhere (useful for testing with a hand-written file).
The file is read every 3 seconds with a timer, and again whenever the popover opens or you click Refresh. A file watch is deliberately not used: the daemon replaces the file atomically by rename, which would leave an inode-based watch pointing at a dead file.
Hidden-item warning
After every refresh the app asks the window server whether the status item’s
window is on screen (CGWindowListCopyWindowInfo, kCGWindowIsOnscreen). When
the menu bar is full, macOS parks the newest item under the notch or off the
end of the bar: the app keeps running and logging, but nobody can see it. On
the transition from visible (or never seen) to hidden the app:
- logs one line to stderr,
agent-watchdog-menubar: status item is hidden (menu bar full or behind the notch); ..., with the window position and width it measured; - posts one notification,
agent-watchdog menu bar icon is hidden, through Notification Center viaosascript(display notification), with the same fixes as the Troubleshooting note below; - adds an
Icon hidden since 19:14 (menu bar full or behind the notch)notice under the popover’s header, for anyone who reaches the popover through a menu bar manager.
It warns again only after the item has been visible and disappears again, so a 3-second refresh loop never repeats it. The probe is skipped while the popover is open, because a menu bar manager reveals hidden items for exactly that long and the item would otherwise flap. A reading the window server has not laid out yet (zero width, as on the very first refresh after launch) decides nothing.
Daemon states
The popover’s header reports one of these, derived only from the file and the clock:
| State | Condition | Header line |
|---|---|---|
| running | now - at <= 2.5 x intervalMs and stoppedAt is null |
Daemon running (last poll 12s ago) |
| stale | file exists, stoppedAt is null, last poll older than 2.5 x the interval |
Daemon not responding (last poll 4m ago) |
| ahead of clock | at is more than 5 s ahead of this Mac’s clock, stoppedAt is null |
Snapshot time ahead of this Mac's clock; daemon state unknown (sessions shown from the last poll, icon muted) |
| stopped | stoppedAt is set (the daemon shut down cleanly) |
Daemon stopped at 19:20 |
| missing | no file at the path | Daemon not running / Start it with: agent-watchdog watch (or agent-watchdog install) |
| unreadable | file exists but is not valid status JSON | Status file unreadable / the decoding error |
intervalMs falls back to 30000 when the file does not carry it. Unknown JSON
fields and unknown enum values (level, lifecycle, source, kind,
location) are tolerated so a newer daemon never breaks an older app.
Handoffs in the status file
Each session may carry a handoff field: null (or absent, in files from an
older daemon) when none has been written, otherwise
{ "path": "/abs/handoff-<sessionId>.md", "writtenAt": "<ISO 8601>", "location": "repo" | "scratchpad" | "external" }
(Codex handoffs are named handoff-codex-<sessionId>.md). A handoff object
without a path is treated as no handoff. The daemon also records an event of
kind handoff with level info when it first sees one appear.
A daemon with the handoff coordinator also writes an optional actions
field per session (schemaVersion: 1): whether the session’s harness can
generate a handoff (capability: supported, unsupported, unknown),
why not, and the latest request its journal knows. The row’s Generate
button is enabled only for supported; a missing field, another schema
version, or an unknown value reads as unknown and disables only Generate
(This daemon does not report handoff generation for this session).
Generate runs agent-watchdog handoff generate (found the same way the
Settings window finds the CLI: AGENT_WATCHDOG_CLI, the launch agent’s
program, then PATH) with the daemon’s configFile.path forwarded as
--config and its config.settings["state-file"] as --state-file, reads
the first result line, and leaves the helper running if it keeps settling a
timed-out request. See Generating a handoff.
The daemon’s optional sessionActivity and childSessions sections feed the
activity totals and the subagent rows. Each decodes on its own: an absent,
unsupported, or malformed section disables only what it feeds, never the
allowance cards or the session rows.
Popover
Click the icon to open the popover; click it again, press Escape, or click anywhere outside it to close it. Controls inside keep it open, and a failed command or a session that vanished is reported in a message line under the header with a dismiss button, never by closing the page. The page starts 520 points wide (narrower on a small screen) and is never taller than the screen below the menu bar. The header and footer stay pinned; the allowance cards take at most 40% of the height and scroll on their own, and the session list scrolls beneath them. Expanded rows, the scroll position, and keyboard focus survive every refresh. The page follows light and dark appearance, the system text size, increased contrast, and reduce motion; Tab moves through the controls, and every meter and control carries a spoken label. Opening the popover makes the app active so Escape and the keyboard reach it; when the popover closes (Escape, a click on the icon, or switching to another app), focus returns to the app you were using. Opening Settings from the popover keeps focus on the settings window.
Header
- Title and Settings.
Agent Watchdog, with a gear button that opens the settings window. - Daemon state with a coloured dot (see Daemon states)
and, beneath it, the config summary
warn 35% · critical 75%(with· dry-runwhen the daemon runs in dry-run mode), or the hint or decoding error for the missing and unreadable states. A snapshot dated more than 5 seconds ahead of this Mac’s clock readsSnapshot time ahead of this Mac's clock; daemon state unknown, never running: its rows are shown as from the last poll, the icon is muted, and the allowance cards say the daemon state is unknown. - Two times, kept apart.
Status read 0s agois the app’s last successful read of the file;Snapshot written 18s agois when the daemon wrote it (at). Hover either for the exact time and zone. Neither claims every metric below is fresh; each metric carries its own time. - Notice lines, in this order, only when they apply:
Config file ignored: <message>while the daemon runs on flags and defaults because its config file failed to load, thenRestart daemon to apply settingswhen the config file changed on disk after the daemon read it (configFile.changedSinceLoad). Both repeat what the daemon published and show only while the daemon is running or stale. The popover does not show the config file’s path; the settings window shows it in its red banner and in its footer.Icon hidden since 19:14 (menu bar full or behind the notch)while the status item is hidden (see Hidden-item warning).Status file unreadable (<time>): <reason>when the last read failed, followed byShowing the last successful read (status read 1m ago)when an earlier read is still on screen.Sessions from the daemon's last pollwhile the daemon is not running or its snapshot is dated ahead of the clock, so the rows below are history, not live state.- One line per harness whose discovery failed (
providerFailures).
Allowances
One card per provider source, OpenAI / Codex and Anthropic / Claude, with a
state badge, the account label, and how confident the source identity is. Each
card has one meter per window the provider reported (a five-hour window stays
labelled five-hour; no window is invented), each with its own percentage,
state badge, reset time, and update age: Updated 20s ago when the provider
reported when it measured, or Received 2m ago · age unverified when only the
receipt time is known. Unknown or historical readings say so, and a card shows
why its alerts are unavailable. See Account usage for the
sources and their limits.
Session activity
The heading line counts what the list holds, for example
2 sessions · 2 subagents · 12 inactive: the active families, the subagents
inside them, and the families in the collapsed Inactive section (the same
number its header shows). Beneath it:
- Today’s observed tokens, such as
3.74M tokens Today, withUpdated 18s agofrom the daemon’s activity cutoff. The interval is the current calendar day in the Mac’s time zone; a different daemon time zone is named. When the payload’s day is not today on this Mac’s clock, for example just after midnight before the daemon publishes the new day, the interval is named by its date and marked,2026-09-26 · not today, the total is never shown as complete, and every “today” in the section becomes “on 2026-09-26”. A total with partial coverage carries· partialbeside the number. When more than one model provider contributes, a bar and a line split the total by provider (OpenAI 1.48M tokens). Claude activity carries no model provider today, so it readsClaude, provider not reported; a harness is never mapped to a provider. - What the figure is:
Observed on this Mac · family totals include subagents once · Local tokens, not plan usage or cost. These are the tokens the agents’ own transcripts recorded on this Mac today, each session’s own work counted once. They are not a share of any plan allowance, not billed cost, and not activity from other devices; the allowance cards above are the plan figures. - Coverage:
Complete for this Mac's enabled harnessesonly once every transcript in scope has been read to its end, orPartial: <reasons>(for examplecollection has not finished reading every transcript,transcript scanning is turned off, ora transcript format is not understoodfor a Claude line too long to read or a malformed line), withN sessions not measuredappended when some sessions have no figure. A partial or unavailable total is never shown as zero;0 tokensappears only under complete coverage.
The headline is the sum of each session’s own total as the daemon published
it; the daemon does not yet publish an interval total of its own. Before the
first read the section says Local activity not read yet. A daemon that
publishes no activity (an older daemon, or one still finishing its first
collection pass) shows The daemon has not published local activity; an
unsupported activity schema or measurement names its version, and a malformed
section gives its reason. In every one of those cases the allowance cards and
session rows keep working.
Below the totals, one row per active session family, worst context first, then the Inactive section (below):
- Collapsed row. The disclosure chevron; the directory name; harness,
model, and today’s tokens (
1.17M tokens incl. subagentson a root, which is its family total, each member’s own work once), followed by· partialwhen that figure’s coverage is partial and· not todaywhen the payload’s day is over (the meta line wraps rather than cut these marks off); the number of subagents; a lifecycle badge (running,idle,needsInput,unknown); the context badge (Context 81%, tinted by the level the daemon derived) withContext updated 1m agofrom that session’s own observation time; the cache state (Cache expires in ~41m,Cache expired 12m ago, orCache: not reportedfor Codex, which reports no cache deadline); the Focus button; and the handoff controls (below). The cache time is an estimate, last activity plus the cache TTL, not a reading from the provider. Focus runscmux select-workspace --workspace <workspaceId>and then, when the session has a surface id,cmux focus-panel --panel <surfaceId> --workspace <workspaceId>(both withCMUX_QUIET=1); it is disabled, with the reason as help, for sessions without a workspace id (transcript-scan sessions) and for subagents. - Expanded row. Click the row’s title line (the chevron, name, and
details). The detail shows the context
meter with tokens used of the window, last activity, the directory, the cache
deadline with
Cache observation time unknown, the handoff location and path, a subagent’s own lifecycle evidence, andLocal activity todaywith that session’s own work and coverage. Subagent rows appear indented beneath, each with its own context, cache, and handoff state read from its own transcript, never copied from the parent. A Claude subagent readsSubagent status unknown · no evidence, because Claude writes no completion marker a subagent’s status could be read from. When the daemon’s latest subagent read for a harness failed, its subagent rows are kept and markedRetained · the latest Claude subagent read failed · rows from a read 3h ago. A family whose parent did no work of its own today still shows the family total its subagents recorded; the parent’s detail then readsNo own work recorded today. Expanding one family never collapses another. - Inactive (N). One header row with a disclosure chevron, collapsed by
default. It holds every family in which no member is active: the daemon
marks a live session or subagent inactive when it is idle (or its lifecycle
is unknown) and its last activity is at least
inactive-afterold (default 30 minutes; set it in Settings or with--inactive-after). A session with a warm prompt cache worth handing off stays in the active list until its cache expires, so a “Prompt cache expiring” notification always names a visible row. For Claude, a transcript still being written (a long tool call) counts as activity. Running sessions, sessions waiting for input, sessions with an unknown last activity, and sessions from a daemon too old to say are never inactive. A family is never split: one active member, parent or subagent, keeps the whole family above the header. When a hidden family’s context is at warning or critical the header carriesworst context critical(orwarning), so collapsing never hides that something needs attention; notifications fire as usual. Expanded, inactive families come first, latest activity first, as ordinary family cards with the same disclosure, Focus, Generate, and View controls. Click the header, or press Space (or Return on macOS 14 and later) when it has keyboard focus; it sits in the Tab order after the active families. The open or closed choice is remembered across popover opens and app restarts. When every family is inactive the list readsNo active sessionsabove the header. - Earlier today · no current context. Inside the Inactive section, after
the inactive live families: sessions the daemon counted today but no longer
lists as live (finished sessions, or ones past the stale window), latest
activity first. When the payload’s day is over the heading names it,
Earlier on 2026-09-26 · no current context. They showNo current contextand their last activity, and offer no Focus or Generate. - Recent allowance events. Up to five plan-allowance notifications, newest first (for example a Codex window crossing its warning percentage). They are allowance events, not local activity, and the list is hidden when there are none. Context notifications and handoff sightings are not repeated here; macOS notifications and the daemon log carry them.
With no sessions the list reads No sessions while the daemon is running,
No sessions in the last poll otherwise, and No session data before any file
was read.
Handoff controls
Every root row has, on the right of its cache state:
- Generate handoff, or Regenerate once a handoff is saved. It asks the session’s harness to write a handoff document now (see Generating a handoff).
- View handoff, which opens the saved file in its default app after
checking it still exists. Open its context menu (Control-click) and choose
Reveal handoff fileto show it in Finder. It is disabled, with a reason, when no handoff is saved or the file is gone. - A status line:
Handoff saved 12m agoorNo handoff saved, and while a request is in flight or has just settled,Requesting a handoff,Handoff request accepted,Generating a handoff,Handoff generated 2m ago,Generation failed: <why>,Not started: <why>, orStill running or unknown: <why>.
Neither button expands or collapses the row, and neither closes the popover. While a request runs, and after it fails, the previous handoff stays viewable.
Generating a handoff
Generate is enabled only when the daemon reports generation as supported for
that exact session (the optional actions field, see
Handoffs in the status file); an existing
handoff file never enables it by itself. A session the daemon reports as
running (mid-turn) keeps it disabled until the turn ends.
A click runs agent-watchdog handoff generate for that session with a new
request id, forwarding the daemon’s config file as --config and its state
file as --state-file so the helper and the daemon share one request journal.
The app reads the helper’s first result line. The helper can keep running
after it answers while it settles a request that is still generating; that is
expected, and the daemon reports the outcome through the status file. The
helper also keeps running, and finishes and records the request, if the menu
bar app quits mid-generation. Repeated
clicks while a request is pending send nothing, and after a restart the journal
refuses a duplicate.
What generation does and does not do:
- It forks the session. Claude Code runs a non-persisted fork of the exact session and Codex an ephemeral fork of the exact thread. The fork reads the saved transcript and writes the handoff; the live session is not stopped, cleared, compacted, or told that a handoff was written. One generation is one model call sized by the session’s context, counted as your own usage.
- Claude Code idle is judged by
claude agents. A session thatclaude agents --jsonlists asidleis dispatched even while cmux reports it waiting for input (Claude Code’s idle notification sets that about a minute into every idle). A listing ofbusyorwaitingis refused and names what it waits for, and a session neitherclaude agentsnor cmux can vouch for, such as one started withclaude -p, is refused as busy. - Codex sessions found only by transcript scan are refused as busy. Codex
has no idle signal of its own, so only a session cmux reports as idle is
dispatched; start Codex in a cmux pane the normal way, through cmux’s
codexwrapper, so cmux tracks it. A scan-only Codex session answersSession busy: session state is unknown, and Generate stays disabled with that reason until the session’s lifecycle changes. - Uncertain settles on its own. When the helper stops waiting before the
generation settles, the row says
Still running or unknown: …and Generate stays disabled until the daemon’s journal settles the request. If the helper and its fork have both died, the daemon marks the request failed on its next check and Generate works again; a helper still alive but wedged stops blocking after about 12 minutes. There is no button to abandon a request. An entry leftuncertainby an earlier build whose helper died mid-generation does not settle; the daemon reference explains how to clear it. - The command-line tool must be reachable. The app and its launch agent do
not share your shell’s PATH. When the Codex CLI is missing, too old, or not
signed in, the reason names
openai-codex-pathunder OpenAI / Codex usage in Settings; set it to thecodexexecutable. The Claude CLI is looked up on PATH and in~/.local/bin, and has no path setting yet. - Subagent rows never generate. Subagents from the daemon’s
childSessionssection sayHandoffs are generated for root sessions only. A Codex subagent the daemon lists as an ordinary session keeps its own capability.
The daemon reference has the exact fork commands, versions, and time limits under Commands and the per-harness gaps under Harness capabilities.
Footer
Refreshrereads the status file now. It never asks a provider for new data; collection runs in the daemon.- The daemon control for the current state:
Stop daemon(running, withRestart daemon to apply settingsbeside it while the daemon reportschangedSinceLoad),Restart daemon(stale), orStart daemon(stopped, missing, unreadable). Start and both restarts runlaunchctl kickstart -k gui/<uid>/com.wholeclove.agent-watchdogand, if that fails (label not loaded),launchctl bootstrap gui/<uid> ~/Library/LaunchAgents/com.wholeclove.agent-watchdog.plist. Stop runslaunchctl bootout gui/<uid>/com.wholeclove.agent-watchdog. When the plist is known to be missing, the noteDaemon not installed (run: agent-watchdog install)replaces the control. Until the app has checked (off the main thread, within one read), it shows the control the daemon state implies. - More holds
Open logs(opens~/Library/Logs/agent-watchdog/in Finder, disabled until the directory exists),Open status file(opens it with its default app; its help shows the path), andQuit.
Every external command is launched with an executable path and an argument
array, never a shell string, off the main thread; the page updates when the
command finishes. cmux is resolved from /opt/homebrew/bin/cmux,
/usr/local/bin/cmux, then PATH.
Account usage
The popover shows plan allowances in their own cards, above and separate from session context and local activity, when monitoring is enabled. By default, monitoring follows each enabled harness; an explicit usage setting overrides that choice. OpenAI/Codex and Anthropic/Claude have separate groups with window percentages, reset information, data age, and collection health. Unknown or historical readings are labeled accordingly. The app renders the daemon’s alert levels and source capabilities; it does not calculate quota thresholds itself. The status item remains icon only and untinted.
Enable each provider and configure warning, critical, and exhaustion alerts in Settings…. Warning and critical percentages default to 40% and 80%. Monitoring and notification preferences are independent, so you can display usage without receiving usage notifications. Save and restart the daemon to apply changes, following the existing Settings workflow.
Codex can supply fresh allowances through its local app server, and Claude through Claude Code’s own usage command, which also reports per-model weekly windows. Claude’s status-line bridge, the fallback when that command is off or failing, supplies no verified observation time, so its readings are historical and never alert. Settings explains source limitations separately from saved preferences and temporary collection failures. Offline sources do not erase your preferences.
Refresh rereads the daemon’s status document; it does not trigger an account request. See plan-usage setup and the Claude bridge.
Settings window
The gear button in the popover’s header opens one window (a second click
brings the same window to the front) that shows every daemon setting, grouped the way the
daemon’s settings metadata groups them. Nothing in the window is hand-built
from the option list: it runs agent-watchdog config schema, decodes the
x-groups of that document, and renders one row per setting from its control
kind. Adding an option to apps/watchdog/src/cli/options.ts and regenerating
the schema adds it to the window with no Swift change. Per control:
| Control | Row |
|---|---|
| toggle | switch |
| number, percent | numeric field with a stepper, bounded by the schema’s min, max, integer |
| duration, path | text field (path rows add a Choose... button) |
enum (multiple) |
one checkbox per allowed value, written in the schema’s order |
| list | one text field per item with remove buttons, plus Add |
| anything else | plain text field holding the raw JSON, so a newer daemon’s control still shows |
Each row shows the help text from the metadata, whether the value comes from
the config file or is the built-in default, an edited mark once changed, a
Reset to default button that removes the key rather than writing the default
value, and its validation error inline. Validation mirrors the schema (type,
range, whole numbers, the duration syntax, enum members); the cross-field
rule (critical above warn) stays with the daemon’s config validate. Clearing
a text field or emptying a list also removes the key.
Save. Save (Cmd-S; Return never saves) is enabled once something is
edited and every local check passes. It writes the form to
<config path>.<pid>.tmp next to the config file, runs
agent-watchdog config validate <that file> --json through
the daemon CLI, and only then renames the candidate over the config file, so
the daemon never sees a partial or invalid file. When the daemon rejects the
candidate, every field its error names is highlighted with the daemon’s
message (the cross-field rule, critical above warn, names both), messages that
name no field appear above the form, the candidate is removed, and the config
file is left as it was. After a successful save the footer reads Saved at 19:14. Restart the daemon to apply. and, when the launch agent is installed,
a sheet offers Restart Daemon (the same launchctl kickstart -k the popover’s
restart uses) or Later. Restart daemon is also always available in the
footer while the daemon is installed. Cancel (or Cmd-W) closes the window
without writing.
What the daemon is running with. Every row shows Daemon is running with: <value> from the status document’s config.settings (durations as
45s, lists joined with commas, not set for an optional setting without a
value) so the saved value and the live value can be compared. Rows whose
configSources entry is cli are disabled with the note “Set by a
command-line flag in the launch agent; reinstall the daemon to manage it
here”: an older install baked the flag into the plist, and a flag always wins
over the file. Above the form, a red banner repeats the daemon’s configError
while it runs on flags and defaults because the file failed to load, and an
orange banner with a Restart daemon button appears while the daemon reports
changedSinceLoad (the file on disk is newer than the one it read). Both
banners come from the status document, which the app rereads every 3 seconds,
so a restart clears them within a poll.
Where the file lives. The window edits, in order: the file named by
AGENT_WATCHDOG_CONFIG_FILE; the file the daemon’s status document names in
configFile.path (so a daemon started with --config other.json is edited
where it reads); else ~/.config/agent-watchdog/config.json. The footer shows
the path in use. When the file does not exist the daemon’s defaults are shown
and the first save creates the file and its directory.
Finding the daemon CLI. The window needs the daemon’s command line for
config schema and config validate. It takes, in order: the executable named by
AGENT_WATCHDOG_CLI in the environment; the node and script paths from
ProgramArguments in the launch agent plist
(~/Library/LaunchAgents/com.wholeclove.agent-watchdog.plist, the file
agent-watchdog install writes); then agent-watchdog in
/opt/homebrew/bin, /usr/local/bin, or PATH. When none exists, or the
command fails (for example a daemon built before config schema existed), the
window shows the exact command that failed and its stderr, with a Try again
button, instead of a form.
Three environment variables exist for checking the window without clicking:
AGENT_WATCHDOG_MENUBAR_OPEN_SETTINGS=1 opens it at launch,
AGENT_WATCHDOG_CONFIG_FILE=/some/config.json points it at a hand-written
file (the footer shows the path in use), and
AGENT_WATCHDOG_MENUBAR_SAVE_ON_OPEN=1 sets warn-context to 45 once the
window has loaded and runs the whole save pipeline (validate, write) with the
restart offer suppressed, logging the outcome to stderr; it is refused unless
AGENT_WATCHDOG_CONFIG_FILE is set, so it can never touch the real config
file. None is meant for normal use.
The app keeps an invisible main menu (it has no menu bar of its own) so that the standard Edit shortcuts work inside the window’s text fields and Cmd-, and Cmd-W reach the settings window.
Permissions
The app needs no macOS permissions. It draws a status item, reads files under
the home directory, opens handoff files through the default app or Finder, and
runs launchctl, cmux, the daemon CLI (config schema and config validate --json for the settings window, handoff generate for Generate
handoff), and (for the hidden-item warning) osascript as the current user.
The handoff helper in turn runs the claude or codex CLI for the fork. It does not use
the notification framework itself, Accessibility, or screen recording; the
window-server query for its own status item needs no permission.
Troubleshooting
The icon is missing on a notched MacBook. When the menu bar is full, macOS hides the newest status items behind the notch without any warning of its own. The app is running; there is simply no room. The app notices (see Hidden-item warning) and posts one notification with the fixes:
- Free a slot by quitting another menu bar app or by using a menu bar manager. Third-party status items cannot be dragged off the bar, only reordered with Command-drag, and reordering can push a different item under the notch.
Measured on the machine this was diagnosed on (macOS 15.7, display 1496 pt wide, notch from 668 to 828 pt, leftmost visible item at 857 pt): the bar had left only a 29 pt gap, which is narrower than this app’s 37 pt item, so on that bar only freeing a slot helps.
Confirm the app is alive with
launchctl print gui/$(id -u)/com.wholeclove.agent-watchdog-menubar (when
installed via agent-watchdog install --menubar-bin) or
pgrep -fl agent-watchdog-menubar, and look in its stderr for the
status item is hidden line.
Layout
Four targets in one package; dependencies point inward only (App depends on Dashboard, Application, and Core; Dashboard on Application and Core; Application on Core). ARCHITECTURE.md has the full rule set: what each target may import and own, the ports the app implements, and how views compose inside the dashboard library.
Sources/MenubarCore: Foundation-only library. Status file models and decoder (ISO-8601 with fractional seconds), daemon-state derivation, worst session selection, handoff rows and their enabled state (with an injected file-exists check), hidden-item transitions, all string formatting, the settings schema decoder, the settings form model (values, dirty state, validation, serialization, flag-locked rows, daemon errors), the save pipeline (candidate file,config validate --jsonparsing, atomic rename) with injected I/O, the config notices the popover and window show, and the launch agent plist parser that finds the daemon CLI.Presentation/holds the pure timestamp presentation (typed roles, relative and absolute-with-zone labels, future and malformed handling) and theSessionForestlineage projection (which parent claims are proven, in a stable family order);Domains/Context/holds the composite session identity the dashboard keys rows and actions by. This is whatMenubarCoreTestscovers.Sources/MenubarApplication: Foundation and Combine only, never SwiftUI or AppKit. The ports the app implements (status repository, clock and scheduler, session, handoff and daemon commands, Settings host), the status history that keeps the last good document across a failed read, and the dashboard state:Dashboard/holds the main-actorDashboardStore(read cadence, coalescing, stale-result guard, interaction state, intent handling), the pureDashboardPresenter, the typedDashboardIntent, and the page view data;Allowances/,Activity/, andContext/hold the section view data and presenters. Covered byMenubarApplicationTestswith fake ports, which also scans the sources to keep the import rules honest.Sources/MenubarDashboard: the SwiftUI dashboard library.DesignSystem/holds the tokens (semantic colors through system colors, text styles, spacing, radii, motion that honors reduce motion), atoms (StatusDot,SemanticBadge,IconButton,NumericLabel) and molecules (Meter,LabeledMetric,UpdatedAtLabel,SectionHeading,EmptyState), all taking primitives and callbacks rather than status-file types.Previews/holds debug-only fixture data and galleries of every state.Features/Allowances/holds the provider allowance cards: one card per source, one meter per reported window with its own named state, reset time and update age, and a section notice when the cards show retained data.Features/Activity/holds the session activity section: expandable session families (ActivitySection,FamilyDisclosure,SessionRow,SubagentRow) whose collapsed rows already show the context badge with its own observation time, the cache state, and the focus, Generate and View handoff controls;Features/Context/Components/holds those pieces (ContextMeter,CacheStatus,SessionActions,HandoffControls).Composition/holds the page (DashboardView) with its pinned header and footer; the library never reads a file or runs a process. Covered byMenubarDashboardTests.Sources/MenubarApp: the AppKit executable.Composition/wires adapters to ports, including the Settings window as the Settings host;Hosting/holds the status item controller and the dashboard popover;Infrastructure/holds the status-file reader, command runner, cmux and launch agent adapters, notifier, and timer; plus the window-server visibility probe, main menu, and the SwiftUI settings window and its window controller. Not unit tested.Tests/MenubarCoreTests,Tests/MenubarApplicationTests, andTests/MenubarDashboardTests: the XCTest suitesswift testruns.
CI
This workspace is not covered by CI. Its package.json scripts run
swift build / swift test only on Darwin and print skip: macOS only
elsewhere, so the root yarn build, yarn test, yarn lint, and
yarn typecheck stay green on Linux runners without building the app. Run the
build and tests locally on a Mac before merging changes here.
Compact allowance cards
Each provider card keeps its usage bars, percentages, states, and reset times visible.
Expand Details for account identity, collection diagnostics, individual update
ages, exact reset timestamps, and alert limitations. Session and weekly windows
share the same compact card. Relative ages and countdowns use minutes, with
<1m for less than one minute; hover details retain exact timestamps.