Skip to content
agent-watchdog

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 via osascript (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.

  • 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-run when 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 reads Snapshot 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 ago is the app’s last successful read of the file; Snapshot written 18s ago is 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:
    1. Config file ignored: <message> while the daemon runs on flags and defaults because its config file failed to load, then Restart daemon to apply settings when 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.
    2. Icon hidden since 19:14 (menu bar full or behind the notch) while the status item is hidden (see Hidden-item warning).
    3. Status file unreadable (<time>): <reason> when the last read failed, followed by Showing the last successful read (status read 1m ago) when an earlier read is still on screen.
    4. Sessions from the daemon's last poll while the daemon is not running or its snapshot is dated ahead of the clock, so the rows below are history, not live state.
    5. 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, with Updated 18s ago from 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 · partial beside 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 reads Claude, 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 harnesses only once every transcript in scope has been read to its end, or Partial: <reasons> (for example collection has not finished reading every transcript, transcript scanning is turned off, or a transcript format is not understood for a Claude line too long to read or a malformed line), with N sessions not measured appended when some sessions have no figure. A partial or unavailable total is never shown as zero; 0 tokens appears 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. subagents on a root, which is its family total, each member’s own work once), followed by · partial when that figure’s coverage is partial and · not today when 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) with Context updated 1m ago from that session’s own observation time; the cache state (Cache expires in ~41m, Cache expired 12m ago, or Cache: not reported for 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 runs cmux select-workspace --workspace <workspaceId> and then, when the session has a surface id, cmux focus-panel --panel <surfaceId> --workspace <workspaceId> (both with CMUX_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, and Local activity today with 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 reads Subagent 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 marked Retained · 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 reads No 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-after old (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 carries worst context critical (or warning), 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 reads No active sessions above 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 show No current context and 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 file to 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 ago or No 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>, or Still 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 that claude agents --json lists as idle is dispatched even while cmux reports it waiting for input (Claude Code’s idle notification sets that about a minute into every idle). A listing of busy or waiting is refused and names what it waits for, and a session neither claude agents nor cmux can vouch for, such as one started with claude -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 codex wrapper, so cmux tracks it. A scan-only Codex session answers Session 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 left uncertain by 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-path under OpenAI / Codex usage in Settings; set it to the codex executable. 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 childSessions section say Handoffs 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.

  • Refresh rereads 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, with Restart daemon to apply settings beside it while the daemon reports changedSinceLoad), Restart daemon (stale), or Start daemon (stopped, missing, unreadable). Start and both restarts run launchctl kickstart -k gui/<uid>/com.wholeclove.agent-watchdog and, if that fails (label not loaded), launchctl bootstrap gui/<uid> ~/Library/LaunchAgents/com.wholeclove.agent-watchdog.plist. Stop runs launchctl bootout gui/<uid>/com.wholeclove.agent-watchdog. When the plist is known to be missing, the note Daemon 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), and Quit.

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 --json parsing, 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 the SessionForest lineage 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 what MenubarCoreTests covers.
  • 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-actor DashboardStore (read cadence, coalescing, stale-result guard, interaction state, intent handling), the pure DashboardPresenter, the typed DashboardIntent, and the page view data; Allowances/, Activity/, and Context/ hold the section view data and presenters. Covered by MenubarApplicationTests with 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 by MenubarDashboardTests.
  • 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, and Tests/MenubarDashboardTests: the XCTest suites swift test runs.

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.