Usage and configuration
Install agent-watchdog, check your sessions, and choose when it should alert you. Start with the prebuilt download on Apple silicon, or build from source. If you have already installed it, jump to configuration or troubleshooting.
For command details and data formats, see apps/watchdog/README.md. For menu
bar controls and settings, see apps/menubar/README.md.
What it does
agent-watchdog checks Claude Code and Codex sessions every 30 seconds by default. It computes context usage and prompt-cache expiry from each session’s local transcript and cmux’s session store, then notifies you through macOS notifications at the warning threshold (35%) and critical threshold (75%). The optional menu bar app shows each session’s context, cache, and handoff, your plan allowances, and today’s locally observed token activity, and can ask an idle session to write a handoff.
For Claude Code, it estimates prompt-cache expiry and can alert when an idle session’s cache is about to expire. Codex cache expiry is unavailable; missing metrics are shown as unavailable and do not trigger alerts that depend on them.
Notifications are enabled by default and are the only thing the daemon sends: it never types into an agent’s terminal. When a session crosses the critical threshold or its prompt cache is about to expire, the notification asks you to have the agent write a handoff; see Alerts.
Plan usage in the menu bar
Click the gear in the menu bar popover’s header to open Settings and configure plan-usage monitoring for OpenAI/Codex or Anthropic/Claude. Each follows its matching enabled harness by default; an explicit on or off choice overrides that selection. Each provider has separate warning and critical percentages (40% and 80% by default), notification toggles for those thresholds, and an exhaustion notification toggle. Save your settings, then restart the daemon to apply them. Command-line overrides remain visible in Settings and take precedence over saved values.
Monitoring can stay on while notifications are muted. Usage appears in its own cards at the top of the popover, separately from session context and local activity; the menu-bar icon stays icon only. Refresh rereads the daemon’s status file. Collection runs independently in the daemon, so Refresh does not force a provider request.
Codex monitoring uses the signed-in account in the configured Codex home and reads its allowance through the local Codex app server. It does not send a model turn. Fresh, attributable readings can trigger alerts; unavailable, expired, or stale readings cannot. A failed collection is shown separately from session monitoring health.
The installer sets up both usage sources
for enabled providers, preserving explicit settings and existing Claude renderers.
Provider sign-in remains a user step; the Claude status-line bridge also needs a first supported sample.
Use install --print to preview or install --no-setup-usage for manual setup.
Claude monitoring runs Claude Code’s own usage command in the background every five minutes, without sending a model turn. It reads the 5-hour, 7-day, and per-model weekly allowances (such as a Fable weekly limit) with a known reading time, so fresh readings can trigger warning and critical alerts. When that read is turned off or fails, the popover falls back to the status-line bridge, whose readings have an unknown age and never alert. See the Claude usage probe and the bridge setup instructions.
Plan usage only reads allowances and reports them; it never stops a session or selects a model. The CLI’s session status report does not include account-usage reporting.
Local activity in the menu bar
Below the allowance cards, the popover totals the tokens your agents used on
this Mac today, per session and per family of a session and its subagents. The
daemon collects them from the same local transcripts it already reads, on its
own bounded timer, and publishes them only in the status file; the CLI’s
status and watch output never include them.
These are observed local tokens, not plan usage or cost, and the popover says so beside the total. The allowance cards are what your plan reports; the activity total is what the transcripts on this Mac recorded. The two are not comparable: activity leaves out other devices and other tools, counts input and output tokens rather than billed units, and says nothing about which share of an allowance a session used. Family totals count each member’s own work once, so a subagent is never added twice.
Coverage is shown beside the total. Complete for this Mac's enabled harnesses means every transcript in scope was read; Partial names why not
(collection still catching up after the first start, transcript scanning
turned off, a transcript that could not be read). A partial total is never
shown as zero, and a partial figure carries · partial beside it, on the
total and on each row. Coverage reads complete only once every transcript has
been read to its end. Sessions that finished earlier today stay in the totals
and appear under Earlier today · no current context inside the collapsed
Inactive section at the bottom of the list. That section also holds idle
sessions with no activity for inactive-after (default 30 minutes). A family
with any running, waiting, or recently active member stays above it, and so
does a session with a warm prompt cache worth handing off, until that cache
expires. The popover remembers whether you left the section open. Just after midnight,
until the daemon publishes the new day, the previous day’s figures are named
by their date and marked not today (Earlier on 2026-09-26 for the heading),
never shown as today’s. See the
menu bar reference for every
state and the daemon reference
for what each harness supplies.
Prerequisites
- Prebuilt download: an Apple silicon Mac with macOS 13 or newer. The package includes the runtime, so you do not need Node, Yarn, or Swift.
- Sessions: Claude Code or Codex in cmux, with its agent hooks active. Transcript scanning can find sessions outside cmux, but their lifecycle is unknown and the menu bar cannot focus them.
- Building from source: Node 26 (
nvm use) and Yarn 4.11, vendored in the repository. Ifyarnis unavailable, usenode .yarn/releases/yarn-4.11.0.cjsfor the commands below. - Building the menu bar app: macOS 13 or newer and the Xcode command line tools with Swift 5.9 or later.
To install the Swift toolchain, run xcode-select --install. Check the installed
version with swift --version.
Download a prebuilt build
The download includes the daemon, menu bar app, settings schema, and installer. The installer checks for macOS and Apple silicon before making changes. Download and install it with:
curl -fsSL https://agent-watchdog-downloads.s3.us-east-2.amazonaws.com/agent-watchdog-darwin-arm64.tar.gz | tar -xz
./agent-watchdog/install.sh
install.sh strips the macOS quarantine flag from the unpacked tree, copies
it to ~/.local/share/agent-watchdog, symlinks agent-watchdog and
agent-watchdog-menubar into ~/.local/bin, and then runs agent-watchdog install to register the launch agent, the same install documented in
“Install as a background service” below. Pass --no-install to stop after
linking, and put flags for agent-watchdog install after --:
./agent-watchdog/install.sh --no-install
./agent-watchdog/install.sh -- --warn-context 50 --critical-context 80
If you downloaded the tarball with a browser instead of curl, macOS
quarantines it; install.sh clears that automatically, but if you skip
install.sh and run the binaries directly, clear it yourself first:
xattr -dr com.apple.quarantine agent-watchdog
The launch agent for a downloaded install runs the installed agent-watchdog
binary directly, with watch as its only argument, so there is no separate
Node runtime to keep around: nothing breaks if you later remove or change
Node elsewhere on the machine. (A from-source install still bakes the
absolute path of whichever node ran install; see “Troubleshooting” for
that case.)
To upgrade, download the tarball again and run the same two lines. install
migrates settings the same way for a downloaded build as for a from-source
one (see “Older installs” under “Install as a launchd agent” in
apps/watchdog/README.md).
Build from source
Skip this section if you installed the download. Its commands are linked into
~/.local/bin; make sure that directory is on your PATH. In the examples below,
use agent-watchdog wherever a source build uses
node apps/watchdog/dist/bin/agent-watchdog.js.
For a source build, first clone the repository:
git clone https://github.com/Wholeclove/agent-watchdog.git
cd agent-watchdog
From the repo root:
nvm use
yarn install
yarn build
yarn build compiles the daemon to apps/watchdog/dist/. The CLI entry point
is apps/watchdog/dist/bin/agent-watchdog.js. The daemon has no runtime
dependencies.
The menu bar app is a Swift package outside the TypeScript build graph, so build it separately:
yarn workspace @agent-watchdog/menubar build
That produces apps/menubar/.build/release/agent-watchdog-menubar, a single
executable with no app bundle.
Until you run link (below), invoke the daemon as
node apps/watchdog/dist/bin/agent-watchdog.js. After link, plain
agent-watchdog works from any directory.
Run it once by hand
Start with status. It discovers sessions and prints a table, then exits. It
never notifies and never touches the state or status files.
node apps/watchdog/dist/bin/agent-watchdog.js status
PROVIDER SESSION DIR MODEL CONTEXT PCT STATE LAST CACHE EXPIRES SURFACE HANDOFF
claude aaaaaaaa agent-watchdog claude-fable-5-1 136,239/1,000,000 14% running 18s in 59m 11111111 repo
claude bbbbbbbb cmux-remote claude-opus-5 127,597/1,000,000 13% needsInput 1m in 58m 22222222
How to read it:
| Column | Meaning |
|---|---|
SESSION |
First 8 characters of the session id. Use it with --session. |
DIR |
Basename of the session’s working directory. |
CONTEXT |
Tokens in context over the estimated window for that model. |
PCT |
Context usage. The thresholds compare against this number. |
STATE |
Lifecycle from the cmux store: running, idle, needsInput, or unknown. Sessions found by transcript scan show unknown (scan). A Claude Code session cmux reports needsInput shows idle when its transcript shows the last turn ended with no tool call open, or was interrupted by the user, because cmux records Claude Code’s idle notification as waiting for input. |
LAST |
Time since the last assistant turn. |
CACHE EXPIRES |
When the daemon expects the prompt cache to lapse: in 59m while it is ahead, 12m ago once it has passed. This is computed as last activity plus the cache TTL, not observed from the API. |
SURFACE |
First 8 characters of the cmux surface id the menu bar uses to focus the session, or - for scanned sessions (the menu bar cannot focus them). |
HANDOFF |
Where the session’s handoff file was found: repo (working directory), scratch (Claude session scratchpad), or external (--codex-handoff-dir). Blank when there is none. |
Rows are sorted by percentage, highest first. With no sessions the output is
No active sessions found.
Next, run one poll of the real daemon logic in dry-run mode. This evaluates the rules and logs what it would do, but sends no notifications.
node apps/watchdog/dist/bin/agent-watchdog.js watch --once --dry-run --verbose \
--state-file /tmp/docs-scratch-state.json
2026-09-11T19:08:09.080Z info watching every 30s (warn 35%, critical 75%, cache lead 10m, dry-run)
2026-09-11T19:08:09.088Z debug claude aaaaaaaa 14.0% running store actions=0
2026-09-11T19:08:09.088Z debug claude bbbbbbbb 12.8% needsInput store actions=0
2026-09-11T19:08:09.089Z info stopped
Every log line is <timestamp> <level> <message>. info and debug go to
stdout; warn and error go to stderr. --verbose adds the debug lines,
including one per session with its percentage, lifecycle, discovery source, and
how many actions the rules produced. A dry-run notification shows up as
dry-run notify ....
Why the extra flag: watch persists alert state even with --dry-run and
--once, so a hand run against the default state file would mutate the
installed daemon’s alert state. Point hand runs at a scratch state file. A
one-shot run is otherwise self-contained: --once never writes the status file
unless you pass --status-file <path> explicitly, so the menu bar app keeps
showing the installed daemon.
A hand run reads the same config file as the installed daemon
(~/.config/agent-watchdog/config.json, see “Configuration file”), so it runs
with your saved thresholds and other settings unless a flag overrides them.
Add --no-config to run on the built-in defaults alone.
A long-running hand run (no --once) is different. It would write the default
status file every poll, so give it --no-status-file (or its own
--status-file).
For machine-readable output, add --json. Each poll becomes one JSON line on
stdout and all log lines move to stderr. The sample below is pretty-printed for
reading; the real output is a single line per poll:
node apps/watchdog/dist/bin/agent-watchdog.js watch --once --json --dry-run \
--state-file /tmp/docs-scratch-state.json 2>/dev/null
{
"at": "2026-09-11T19:08:09.134Z",
"sessions": [
{
"provider": "claude",
"sessionId": "aaaaaaaa-...",
"cwd": "/Users/me/projects/agent-watchdog",
"model": "claude-fable-5-1",
"contextTokens": 140152,
"contextWindow": 1000000,
"contextPct": 14.0152,
"lastActivityAt": "2026-09-11T19:07:35.035Z",
"cacheTtlMs": 3600000,
"cacheExpiresAt": "2026-09-11T20:07:35.035Z",
"lifecycle": "running",
"source": "store",
"surfaceId": "11111111-...",
"workspaceId": "33333333-...",
"pid": 78542,
"transcriptPath": "/Users/me/.claude/projects/.../aaaaaaaa-....jsonl",
"handoff": null,
"actions": []
}
]
}
actions lists what the rules decided for that session this poll (notify,
log, or handoff-written entries). handoff is the session’s handoff file
when one exists (see “Handoff files” under “Alerts”), in
the same { path, writtenAt, location } shape as the status file. This per-poll document is the raw internal snapshot, with
process details included. It is not the status-file schema; see “Status file
and JSON output” for the difference.
Install as a background service
install writes a launchd agent that runs watch at login and keeps it alive,
then loads it. Build first, then install:
node apps/watchdog/dist/bin/agent-watchdog.js install
Settings flags given to install are not baked into the launch agent. They go
into the config file, ~/.config/agent-watchdog/config.json (see
“Configuration file”), which the daemon reads at startup. So this:
node apps/watchdog/dist/bin/agent-watchdog.js install --warn-context 40 --critical-context 80
writes "warn-context": 40 and "critical-context": 80
into the file and installs a plist whose arguments are just watch and
--tolerate-config-error. You do not need to pass settings to install at
all: write the file by hand, or use the settings window, before or after
installing.
What install does:
- Writes the settings flags it was given into the config file. Only those
keys are written; keys already in the file are kept. When the file is
created it gets a
$schemapointer to the checked-inapps/watchdog/schema/settings.schema.jsonin a source checkout, or the shippedschema/settings.schema.jsonnext to the unpacked tree for a downloaded install. The merged file is checked the wayconfig validatechecks it, and if it would be invalid (say--critical-context 50over a file that setswarn-contextto 60),installprints the error, writes nothing, and exits with code 2. - Writes
~/Library/LaunchAgents/com.wholeclove.agent-watchdog.plist. ItsProgramArgumentsare the absolute path of thenodebinary that raninstall, the absolute path ofapps/watchdog/dist/bin/agent-watchdog.js,watch, then only the CLI-only flags that apply towatch(--config <path>when you gave one,--no-config,--no-status-file,--json), and always--tolerate-config-error, so a bad config file cannot take the daemon down (see “Configuration file”).RunAtLoadandKeepAliveare on andProcessTypeisStandard. Earlier releases usedBackground, which makes launchd run the daemon at the lowest priority with throttled disk reads; under Spotlight load that delayed its first status by many minutes. - Sets the agent’s
PATHto the directory of thatnodebinary,/opt/homebrew/bin,/usr/local/bin,/usr/bin, and/bin. - Creates
~/Library/Logs/agent-watchdog/and points the agent’s stdout and stderr atstdout.logandstderr.logthere. - Boots out any previously loaded copy and waits until
launchctl printno longer knows the service, polling every 250 ms for up to 5 s (a service that lingers past that only earns a warning). It then loads the new plist withlaunchctl bootstrap gui/<uid>, retrying up to five more times with 500 ms gaps while launchd is still busy with the old instance, falls back tolaunchctl load -wif every attempt fails, and finally verifies the job withlaunchctl print. If launchd did not keep the job,installprints anis not loadedmessage and exits with code 1 instead of claiming success.
--no-config together with a settings flag is an error (exit code 2): with no
file the setting would have nowhere to go, and install never bakes one.
--once, --print, --dir, --help, and --version are never baked.
Changing a setting later does not mean reinstalling. Edit the file (or save it from the settings window) and restart the daemon:
launchctl kickstart -k gui/$(id -u)/com.wholeclove.agent-watchdog
Run install again only when the launch agent itself has to change: a new
node path (the plist’s PATH is fixed at install time), a CLI-only flag such
as --no-status-file, or --menubar-bin.
Older installs. Before the config file existed, install baked every flag
into the plist. When a plist is already installed, install reads it before
replacing it and looks at the settings baked after watch:
- With no config file yet, those settings are moved into the new file, one
notice each (
moved --warn-context 60 from the launch agent into ~/.config/agent-watchdog/config.json). A flag given to thisinstallwins over a baked value of the same setting (replaced --warn-context 60 from the launch agent with --warn-context 40 in ...). - With a config file already present, the baked settings are dropped with a
notice (
dropped --warn-context 60: baked by an older install, and ... already manages settings) and the file is left alone, so a reinstall never silently changes settings the file manages. Set them in the file if you still want them. - A baked flag this build no longer knows is skipped with a notice instead of failing the install.
A plist from an older install keeps working until you reinstall, because a flag always wins over the file. Until then the settings window shows those settings locked (see “Settings window” under “Menu bar app”).
To preview everything without writing or loading anything:
node apps/watchdog/dist/bin/agent-watchdog.js install --print --warn-context 40
--print prints the plist, then any migration notices prefixed with would have, then, when the config file would change, would write <path>: followed
by the file’s new contents.
To also start the menu bar app at login, build it and pass its binary:
yarn workspace @agent-watchdog/menubar build
node apps/watchdog/dist/bin/agent-watchdog.js install \
--menubar-bin apps/menubar/.build/release/agent-watchdog-menubar
--menubar-bin must name an existing executable file, or install exits with
code 2 and a hint. A relative path is resolved against the current directory at
install time and the absolute path is written to the plist. This adds a second
agent, ~/Library/LaunchAgents/com.wholeclove.agent-watchdog-menubar.plist,
with RunAtLoad on, KeepAlive off (so quitting the app sticks until next
login), ProcessType Interactive, the same PATH, and logs at
menubar.stdout.log and menubar.stderr.log in the same log directory.
install --print prints both plists.
Restarting, stopping, and inspecting the daemon with launchctl:
# restart (also picks up a new build; the plist points at dist/, so no reinstall)
launchctl kickstart -k gui/$(id -u)/com.wholeclove.agent-watchdog
# stop until next login or the next bootstrap
launchctl bootout gui/$(id -u)/com.wholeclove.agent-watchdog
# start again after a bootout
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.wholeclove.agent-watchdog.plist
# show state, pid, and last exit status
launchctl print gui/$(id -u)/com.wholeclove.agent-watchdog
The same commands work for the menu bar agent with the label
com.wholeclove.agent-watchdog-menubar.
To remove both agents:
node apps/watchdog/dist/bin/agent-watchdog.js uninstall
uninstall boots out the daemon agent, waits for launchd to report it gone the
same way install does (250 ms polls, up to 5 s), and deletes its plist, then
does the same for the menu bar agent when its plist exists. Because both
commands wait, uninstall && install back to back is safe. The config file is
kept (uninstall prints kept <path>; delete it by hand to reset the settings when one exists), so a reinstall comes back with the same settings.
For day-to-day use, link puts the command on your PATH without installing a
service:
node apps/watchdog/dist/bin/agent-watchdog.js link
agent-watchdog status
link marks the built script executable and symlinks it as
~/.local/bin/agent-watchdog (use --dir for another directory). It replaces an
existing symlink but never touches a real file, and it warns when the directory
is not on your PATH. With --menubar-bin <path> it also symlinks
agent-watchdog-menubar next to it. link does not need to be repeated after a
rebuild.
The rest of this guide uses the linked agent-watchdog command.
Configuration file
The daemon’s settings live in ~/.config/agent-watchdog/config.json. Every
command reads it at startup (watch, status, install, uninstall, and
link); a missing file is fine and means built-in defaults. The file is one
JSON object whose keys are the option names exactly as they appear on the
command line, without the leading dashes:
{
"$schema": "/path/to/agent-watchdog/apps/watchdog/schema/settings.schema.json",
"warn-context": 35,
"critical-context": 75,
"cache-lead": "10m"
}
This example restates the defaults. Merge keys into your existing file; upgrades preserve explicit settings, and keys an older build accepted but this one no longer has are dropped silently. Save, then restart the daemon so it reads the file again:
launchctl kickstart -k gui/$(id -u)/com.wholeclove.agent-watchdog
Value shapes follow how each setting is edited. The placeholder in each
flag’s name below (<duration>, <pct>, <tokens>, <path>, <text>,
<list>) says which kind it is; flags with no placeholder are toggles.
| Kind | JSON value | Example |
|---|---|---|
toggle (verbose, dry-run, scan-transcripts) |
boolean; false is the --no- form |
"scan-transcripts": false |
| duration | string in the flag syntax | "cache-lead": "15m" |
| percent, number | number (a numeric string is accepted too) | "warn-context": 40 |
| path, text | string | "openai-codex-path": "/usr/local/bin/codex" |
list (session, cwd, model-window) |
array of strings | "cwd": ["~/projects/a", "~/projects/b"] |
multi-value enum (harnesses) |
array of the allowed values, instead of the flag’s comma list | "harnesses": ["claude"] |
$schema is optional and ignored by the daemon. Point it at the checked-in
apps/watchdog/schema/settings.schema.json (the shipped
schema/settings.schema.json next to a downloaded install, or at the output
of agent-watchdog config schema) and an editor with JSON Schema support
validates keys, types, and ranges as you type. install writes it with an
absolute path when it creates the file.
Precedence is flag > file > built-in default. A flag on the command line
always wins over the file, for a hand run and for the installed daemon alike;
the file only fills in settings no flag set. The status file reports where
every running value came from in configSources (see “Status file and JSON
output”).
CLI-only flags cannot live in the file. They shape one invocation rather
than the daemon’s behaviour: --help, --version, --once, --json,
--no-status-file, --tolerate-config-error, --config, --no-config,
--print, --dir, and --menubar-bin. A file that names one is rejected
(--once is a command-line flag and cannot be set in the config file), as is
a file with a key that is not a setting at all (unknown setting "warn-contxt"), so a typo cannot silently do nothing. Everything else in the
flag tables is file-eligible; the “Where” column marks the two kinds.
Other files. --config <path> reads another file (a hand run against a
scratch file, or a second daemon with its own settings); install --config <path> bakes that path into the launch agent so the daemon reads the file
install wrote to. --no-config reads no file at all, so the run uses flags
and built-in defaults only; install --no-config bakes it, giving a daemon
that never reads a config file (and refuses settings flags, since they would
have nowhere to go).
Checking a file. agent-watchdog config validate [<path>] loads the file
(the --config path, or the default, when no path is given) through the same
loader and the same checks as the daemon and prints ok with exit code 0, or
the error with exit code 2. A missing file is valid. --json prints
{"ok":true} or {"ok":false,"errors":[{"options":[...],"message":"..."}]},
where options names the settings the error is about (the cross-field check
names both critical-context and warn-context). Errors are reported one at
a time. agent-watchdog config schema prints the JSON Schema (draft 2020-12)
the file is checked against, with a default, description, type, and range
per setting; config alone, or an unknown action, prints a usage line and
exits with code 2. Neither config command reads the file for its own
settings, so both work while the file is broken.
agent-watchdog config validate
agent-watchdog config validate ~/scratch/config.json --json
agent-watchdog config schema | head -40
A bad file (not JSON, an unknown key, a wrong type, a value out of range,
the critical threshold at or below the warning one) is treated like a bad
flag by a foreground run: watch, status, install, uninstall, and
link print config file <path>: <error> and exit with code 2, so the
mistake stops you at the terminal. --no-config is the escape hatch when you
need one of them to run regardless.
The installed daemon is the exception, because install always bakes
--tolerate-config-error into the launch agent: exiting would make launchd’s
KeepAlive restart it into a loop with nothing watching your sessions. With
that flag the daemon starts on its flags and built-in defaults, logs the
failure at error level (config file ignored, running on flags and defaults: ...), sends one notification titled config file ignored with the
error as its body, and publishes the error as configError in every status
document until it is restarted with a fixed file. The menu bar app shows it
as a notice under the popover’s header (Config file ignored: <message>) and
as a red banner, with the file’s path, in the settings window. A hand watch can pass the flag too.
Configuration reference
Every setting is a command-line flag, and every file-eligible setting is also a key in the config file under the same name (see “Configuration file”). Values are validated up front, and a bad value prints a message and exits with code 2, whether it came from a flag or from the file.
Value syntax:
- Durations take a number with a unit:
ms,s,m,h, ord. Units can be chained (2h30m) and decimals are accepted (1.5h). A bare number is seconds (90is 90 seconds). Durations must be greater than zero. In the file they are strings:"cache-lead": "15m". - Percentages are numbers from 0 to 100. Thresholds fire at or above the
value.
--critical-contextmust be greater than--warn-context. - Repeatable flags (
--session,--cwd,--model-window) can be given as many times as you like. In the file they are arrays of strings. - Negation. Boolean flags that default to on are turned off with a
--no-prefix:--no-scan-transcripts. Use--no-openai-usageor--no-anthropic-usageto opt out while that harness is selected. In the file the same settings are plain booleans ("scan-transcripts": false).--no-status-fileis its own flag, because--status-filetakes a path, and it is CLI-only. - Where.
flag or filemeans the setting can be given as a flag or as a key in the config file, and appears in the settings window;flag onlymeans it exists only on the command line.
Commands
| Command | What it does |
|---|---|
watch (default) |
Poll sessions and alert until stopped (or once, with --once). |
status |
Print a one-shot table of sessions and exit; --json prints one status document instead. |
install |
Write settings flags into the config file, install the launchd agent running watch with the CLI-only flags, and load it. --menubar-bin adds the menu bar app. |
uninstall |
Unload and remove the launchd agents. The config file is kept. |
link |
Symlink the built binary into ~/.local/bin (or --dir); --menubar-bin links the menu bar app too. |
config schema |
Print the JSON Schema for the config file and the settings window. |
config validate [<path>] |
Check a config file (default: the --config path or ~/.config/agent-watchdog/config.json); exit 0 with ok, or 2 with the error. --json for a JSON result. |
Flags for all commands
See the generated option reference, including defaults, command scope, config eligibility, and harness applicability.
Flags for watch
See the generated option reference, including defaults, command scope, config eligibility, and harness applicability.
Flags for status
See the generated option reference, including defaults, command scope, config eligibility, and harness applicability.
Flags for config
See the generated option reference, including defaults, command scope, config eligibility, and harness applicability.
Flags for install and link
See the generated option reference, including defaults, command scope, config eligibility, and harness applicability.
Scoping a run with --session and --cwd
Both flags filter sessions after discovery and apply to every command,
including install (which writes them into the config file, so the daemon
runs with them). Within one flag the
values are OR-ed; when both flags are given a session must match both.
Sessions outside the filter are not evaluated and not shown by status.
# one session, by the prefix shown in the SESSION column
agent-watchdog status --session aaaaaaaa
# every session under one project tree, plus one other directory
agent-watchdog watch --cwd ~/projects/agent-watchdog --cwd ~/scratch/wd-test
Context window overrides
The window is an estimate. The daemon resolves it in this order: an exact
--model-window match, the longest-prefix --model-window match, model ids
containing [1m] or ending in -1m (1,000,000), a built-in table by model
prefix (see apps/watchdog/README.md), then --context-window. If a session
shows a suspicious percentage, or more than 100%, override the model shown in
the MODEL column:
# exact id
agent-watchdog status --model-window claude-opus-5=200000
# prefix: every claude-fable- model
agent-watchdog status --model-window claude-fable-=500000
# both, plus a fallback for unknown ids
agent-watchdog watch --model-window claude-opus-5=200000 --model-window claude-fable-=500000 \
--context-window 400000
Alerts
Every poll, each session is evaluated against three rules. A notification is
posted through Notification Center as a macOS notification (osascript,
display notification); the daemon never runs cmux. A notification is the
only thing the daemon sends; it never types into an agent’s terminal. The critical and cache-expiry notifications ask you to have
the agent write a handoff, and “Handoff files” below describes where the daemon
looks for it.
| Rule | Fires when | Notification title |
|---|---|---|
| Warning | Context usage reaches --warn-context. |
Context warning |
| Critical | Context usage reaches --critical-context. Marks the warning as fired too, so you get one alert, not two. |
Context critical |
| Cache expiry | Usage is at or above --cache-min-context, the cache is still alive but expires within --cache-lead, and the session is idle (lifecycle idle, or no activity for --idle-after). |
Prompt cache expiring |
A cache that has already expired never triggers the cache rule; at that point a
handoff is no cheaper than continuing, and status simply shows how long ago
it lapsed (12m ago).
Hysteresis and re-arming. Each rule fires once per crossing. The warning and
critical rules re-arm when usage drops 5 points below their threshold, which
happens after compaction or when the session starts a new context. The cache
rule re-arms when the cache is refreshed (expiry moves back outside the lead
time) or usage drops 5 points below --cache-min-context. The fired flags live
in the state file, so a daemon restart does not re-alert. Sessions not seen for
24 hours are dropped from the state file, so a session that resumes after a
day re-alerts once if it is still above a threshold.
Handoff files
Every poll, the Claude provider checks whether handoff-<sessionId>.md exists,
by stat alone (it never scans the transcript for write calls), at:
<cwd>/handoff-<sessionId>.md, the repo root; or/private/tmp/claude-<uid>/<project-slug>/<sessionId>/scratchpad/handoff-<sessionId>.md, the session’s scratchpad.<project-slug>is the dash-encoded working directory that also names the session’s~/.claude/projects/<slug>transcript directory;<uid>is the daemon’s user id.
When both exist, the newer mtime wins. The result shows up as the session’s
handoff field in the status file and watch --json, and as the HANDOFF
column of status. When a session goes from no file to a file, the daemon logs
one info line and adds one handoff event to the status file’s events, which
the menu bar app shows. The last seen path lives in the state file, so the event
fires once per new file, not every poll, and a daemon restart does not repeat it.
The check repeats every poll: delete the file and the field drops back to
null; write it again and the event fires again. No notification is sent, and a
missing handoff is never alerted on.
The Codex provider does the same for handoff-codex-<sessionId>.md, looking in
the session’s working directory or, when --codex-handoff-dir <path> is set,
in that directory instead (location is then external; the HANDOFF column
shows external). Codex has no scratchpad location.
One file per session means several agents running at once never overwrite each
other’s handoff. If the repo must stay clean, add handoff-*.md to its
.gitignore, or have the agent write to the session’s scratchpad directory
(Claude Code) or to --codex-handoff-dir (Codex) instead; the daemon looks in
both places.
Generating one from the menu bar. Each session row in the popover has
Generate handoff (or Regenerate once one is saved) beside View
handoff. Generate asks the session’s own CLI to write a handoff from a fork
of the saved transcript, to the same file the daemon looks for; the live
session is not interrupted, cleared, or compacted, and one generation is one
model call counted as your own usage. It works only for an idle session: a
Claude Code session that claude agents lists as idle, or one cmux reports
as idle. A Codex session that cmux does not track (found only by the
transcript scan) is refused as busy because Codex offers no idle signal of
its own. When the CLI is not found from the menu bar, set openai-codex-path
for Codex in Settings; Claude Code is looked up on PATH and in ~/.local/bin.
While a request is still settling, the row says Still running or unknown
and Generate stays disabled until the daemon reports the outcome; the helper
finishes even if the menu bar app quits, and the daemon marks a request failed
once its helper and fork are both gone. Only an entry left by an earlier
build can stay stuck; the
daemon reference explains
the manual clear. See
Generating a handoff for
every state and limit.
What a handoff contains. When you ask the agent for a handoff, request a
fixed structure so the next session, or you, can resume without re-deriving
anything: a header with when it was written, the session id (the SESSION
column of status, or the menu bar), and the repo with its branch and commit;
then the current milestone, links to the plans and references it is following
(files under docs/plans, tickets, PRs, design docs), state, decisions, open
questions, and next steps with the most important first:
# Handoff
- Written at: 2026-09-12T14:03:27.000Z
- Session: aaaaaaaa-0000-4000-8000-000000000001
- Repo: /Users/me/projects/agent-watchdog (branch feat/handoff-template, commit 04d43cf)
## Milestone
The objective this session is working toward.
## Plans and references
- docs/plans/handoff-template.md
- PR #12, ticket ABC-42, the design doc being followed
## State
What is done, what is in flight, and what the working tree looks like.
## Decisions
Choices made and why.
## Open questions
Anything unresolved that the next session or the user must settle.
## Next steps
1. The most important step first.
2. Then the rest.
Status file and JSON output
Path and timing. After every poll, including dry runs, the long-running
daemon writes ~/.local/state/agent-watchdog/status.json (change it with
--status-file, disable it with --no-status-file). The write is atomic: a
.tmp file is written next to it and renamed into place, so a reader never sees
a partial document. On a clean shutdown (SIGINT, SIGTERM) the file is written
one last time with stoppedAt set. A failed poll writes nothing, so the file
goes stale instead of claiming there are no sessions.
watch --once is the exception: it never writes the default status file, so a
one-shot hand run cannot mark the installed daemon as stopped in the menu bar.
It writes a status file only when --status-file <path> is passed explicitly,
and that file then carries stoppedAt because the run ends after one poll.
Staleness rule. Readers treat the daemon as not running when
now - at > 2.5 * intervalMs. A non-null stoppedAt means it stopped cleanly.
Two commands, one schema. agent-watchdog status --json prints exactly this
document to stdout without touching any file; in that case daemonPid,
startedAt, and stoppedAt are null, events is empty, and at is now. The
menu bar app reads the same schema from the file. watch --json is different:
it emits the raw per-poll snapshot described under “Run it once by hand”,
including process details that the status file deliberately leaves out.
Schema version 2. Every timestamp is ISO-8601 with milliseconds and a Z
suffix. The table covers the fields most readers need; the
daemon reference lists every field,
including the nullable metrics and the per-session context times.
| Field | Type | Meaning |
|---|---|---|
version |
2 |
Schema version. |
daemonPid |
number or null | Pid of the writing daemon. |
startedAt |
timestamp or null | When the daemon started. |
at |
timestamp | When this document was produced (end of the poll). |
stoppedAt |
timestamp or null | Set only by the final write of a clean shutdown. |
intervalMs |
number | Poll interval. |
config |
object | warnContextPct, criticalContextPct, cacheMinContextPct, cacheLeadMs, dryRun, and settings. |
config.settings |
object | Every file-eligible setting by its option name (warn-context, interval, …) with the value the daemon is running with, normalized: durations in milliseconds, repeatable flags and multi-value enums as arrays, paths expanded, null for an optional setting that is not set (openai-codex-path, cache-ttl, status-file under --no-status-file). The settings window shows these as “Daemon is running with”. |
configFile |
object or null | { path, loadedAt, changedSinceLoad }: the config file the daemon consulted (even one that failed to load), when it read it (its start time), and whether the file’s mtime differs from the one read, or the file appeared or disappeared since, checked before every write. A restart clears it. Null under --no-config. From status --json, loadedAt is now and changedSinceLoad is false. |
configSources |
object | Per file-eligible option name, one of cli (a flag on the daemon’s command line), file (the config file), or default (built in). After an ignored config file every entry is cli or default. |
configError |
object or null | { message, path, at } while the daemon runs on flags and defaults because its config file was ignored under --tolerate-config-error; null when the file loaded or none was consulted. |
sessions[] |
array | One entry per session after --session and --cwd filtering. status --json sorts by percentage. |
sessions[].provider |
string | Harness: claude or codex. |
sessions[].sessionId, shortId |
string | Full id and its first 8 characters. |
sessions[].cwd, dirName |
string | Working directory and its basename. |
sessions[].model |
string | Model id from the transcript. |
sessions[].contextTokens, contextWindow |
number | Tokens in context and the estimated window. |
sessions[].contextPct |
number | Usage percentage, rounded to one decimal. |
sessions[].level |
ok, warn, critical |
Derived by the daemon from its own thresholds, so readers never recompute them. |
sessions[].lifecycle |
string | running, idle, needsInput, unknown. |
sessions[].source |
store or scan |
How the session was discovered. |
sessions[].lastActivityAt, cacheExpiresAt |
timestamp | Last assistant activity and estimated cache expiry. |
sessions[].cacheTtlMs |
number | Detected or forced cache TTL. |
sessions[].surfaceId, workspaceId |
string or null | cmux ids; null for scanned sessions. |
sessions[].handoff |
object or null | { path, writtenAt, location } when the session’s handoff file exists (handoff-<sessionId>.md for Claude Code, handoff-codex-<sessionId>.md for Codex): path absolute, writtenAt the file’s mtime, location repo (working directory), scratchpad (Claude session scratchpad), or external (--codex-handoff-dir). Newer file wins; null when absent. |
sessions[].actions |
object or absent | Optional: whether the menu bar can generate a handoff for the session, and the latest request. Absent from status --json. |
events[] |
array | The last 20 events of the daemon’s lifetime, newest last: notifications and handoff sightings. Kept in memory only; a restart starts empty. |
events[].at |
timestamp | Poll in which the action ran. |
events[].sessionId, shortId, dirName |
string | The session it concerned. |
events[].kind |
notify, handoff |
Notification sent, or a handoff file appeared for the session. |
events[].level |
warn, critical, info |
Notification level; handoff events are always info. |
events[].text |
string | <title>: <body> for notifications; <dirName>: handoff written at <path> for handoff events. |
events[].dryRun |
boolean | True when the action was only simulated. Always false for handoff events. |
Pid, transcript path, and executable path are deliberately absent from the file.
The daemon’s file also carries two optional sections for the menu bar,
sessionActivity (today’s local token activity) and childSessions
(subagent rows); status --json never includes them. See
Local activity and subagent rows.
Menu bar app
The app is an icon-only status item, about 37 pt wide, that opens a popover.
It reads the status file every 3 seconds, and again whenever you open the
popover or click Refresh, and renders what the daemon wrote. The daemon rewrites that file after every poll (every 30
seconds by default, set with --interval), and the app treats it as stale once
it is older than 2.5 times the interval. It never reads transcripts or computes
thresholds itself.
Run it by hand from the repo:
apps/menubar/.build/release/agent-watchdog-menubar
or, after link --menubar-bin ..., as agent-watchdog-menubar. It has no dock
icon; its only window is the settings window (see below). Diagnostics go to
stderr with the prefix agent-watchdog-menubar:.
What the icon shows. The icon is a plain template symbol, drawn in the
menu bar’s own foreground colour rather than tinted, so it stays legible on
any wallpaper. There is no title text and no colour; the glyph shape alone
follows the level of the session with the highest percentage.
| State | Icon |
|---|---|
running, worst session ok, or no sessions |
eye |
running, worst session warn |
eye with warning badge |
running, worst session critical |
eye with filled warning badge |
| stale, stopped, missing, unreadable, or context unknown for some session | crossed-out eye |
Hovering the icon shows the daemon-state line, and the tooltip carries the
percentage: Daemon running (last poll 12s ago) · worst session 81%.
The popover. Click the icon to open it; click the icon again, press Escape, or click outside to close it. From top to bottom:
- Header.
Agent Watchdogand a gear button for Settings; the daemon state (Daemon running (last poll 12s ago),Daemon not responding (last poll 4m ago),Daemon stopped at 19:20,Daemon not running,Status file unreadable, or, when the file’s poll time is more than 5 seconds ahead of this Mac’s clock,Snapshot time ahead of this Mac's clock; daemon state unknown, with its sessions shown as from the last poll, not live) with the config summarywarn 35% · critical 75%beneath it;Status read …andSnapshot written …; and any notices:Config file ignored: <message>,Restart daemon to apply settings, the hidden-icon line, a read error,Sessions from the daemon's last pollwhile the daemon is not running, and discovery failures. The config file’s path is shown in the settings window, not here. - Allowances. One card per provider with a meter per reported window, each with its own percentage, state, reset, and update age (see Plan usage in the menu bar).
- Session activity. Today’s observed local tokens with their coverage
(see Local activity in the menu bar),
then one row per session family, worst context first. A collapsed row shows
the directory, harness, model, today’s tokens, the lifecycle, the context
badge with its own
Context updated …time, the cache state (Cache expires in ~41m,Cache expired 12m ago, orCache: not reportedfor Codex), a Focus button, and Generate and View handoff. The cache time is the session’s last activity plus the cache TTL, not a reading from the API. Click a row’s title to expand it: its detail and its subagents, each with its own context, cache, and handoff. Focus runscmux select-workspaceand thencmux focus-panelfor the session’s surface; it is disabled for transcript-scan sessions and subagents, which have no terminal target. Sessions that finished earlier today follow underEarlier today · no current context, and up to five recent plan-allowance notifications close the list. - Footer.
Refreshrereads the file now.Stop daemon(running),Restart daemon(stale), orStart daemon(stopped, missing, unreadable), plusRestart daemon to apply settingswhile the daemon reportschangedSinceLoad. Start and both restarts runlaunchctl kickstart -k gui/<uid>/com.wholeclove.agent-watchdogand fall back tolaunchctl bootstrapof the plist; Stop runslaunchctl bootout. When the plist is missing,Daemon not installed (run: agent-watchdog install)shows instead. More holdsOpen logs(~/Library/Logs/agent-watchdog/),Open status file, andQuit.
Controls inside the popover keep it open, and errors appear inline under the header. Expanded rows and the scroll position survive every refresh. The menu bar reference describes every line, state, and control.
The app resolves cmux from /opt/homebrew/bin, then /usr/local/bin, then
PATH. Every external command is launched with an argument array, never a shell
string.
Settings window
The gear in the popover’s header opens one window with every daemon setting, grouped the way the
daemon groups them: General, Polling, Sessions, Thresholds, OpenAI / Codex
usage, Anthropic / Claude usage, and Advanced. Nothing in it is hand-built from the option list. The window runs
agent-watchdog config schema, reads the groups from that document, and
renders one row per setting from its control kind: a switch for toggles, a
numeric field with a stepper for percentages and numbers (bounded by the
schema’s range), a text field for durations and paths (path rows add a
Choose... button), one checkbox per allowed value for harnesses, and an
editable list for session, cwd, and model-window. Each row shows the
help text from the schema.
What each row tells you.
- A source badge:
default(the key is absent from the file and the built-in default applies),from file(the file sets it), orset by a flag(see below). The default value is shown as the field’s placeholder. Daemon is running with: <value>, the live value from the status file’sconfig.settings(durations as45s, lists joined with commas,not setfor an optional setting without a value), so the saved value and the value the daemon actually uses can be compared.- An
editedmark once you change it, and aReset to defaultbutton that removes the key from the file rather than writing the default value, so a later change to the built-in default is picked up. Clearing a text field or emptying a list also removes the key. - Its validation error inline, in red. The window checks type, range, whole numbers, the duration syntax, and the allowed enum values as you type; the cross-field rule (critical above warn) is the daemon’s and shows up on save.
Saving. Save (Cmd-S; Return never saves) is enabled once something is
edited and every local check passes. It writes the form to a temporary file
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 it, every field the error names is highlighted with the
daemon’s message, messages that name no field appear above the form, 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 uses) or Later. A
Restart daemon button also stays in the footer while the daemon is
installed. Cancel (or Cmd-W) closes the window without writing.
Banners. Two come from the status file, which the app rereads every 3 seconds, so a restart clears them within a poll:
- A red banner repeats the daemon’s
configErrorwhile it runs on flags and defaults because the file failed to load. - An orange banner with a
Restart daemonbutton appears while the daemon reportschangedSinceLoad: the file on disk is newer than the one it read. You see it after saving, and after any hand edit, until the restart. The popover shows the matchingRestart daemon to apply settingsnotice and button.
Locked rows. A row whose configSources entry is cli is disabled with
the note Set by a command-line flag in the launch agent; reinstall the daemon to manage it here. That happens when a plist from an older install still
bakes the flag, and a flag always wins over the file. To unlock it, run
agent-watchdog install again: with no config file yet, the baked settings
are moved into the file; with a file already present, they are dropped with a
notice and the file’s values (or the defaults) take over. The row unlocks once
the restarted daemon publishes the new sources. See “Install as a background
service”.
Which file, which CLI. The window edits 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;
AGENT_WATCHDOG_CONFIG_FILE in the app’s environment overrides both. The
footer shows the path in use, or No config file yet; defaults shown before
the first save, which creates the file and its directory. To run the CLI it
takes, in order, the executable named by AGENT_WATCHDOG_CLI in its
environment, the node and script paths from the launch agent plist
(~/Library/LaunchAgents/com.wholeclove.agent-watchdog.plist), then
agent-watchdog from /opt/homebrew/bin, /usr/local/bin, or PATH. When
none works (no plist and no linked binary, or a daemon built before config schema existed) the window shows the command that failed and its stderr with
a Try again button instead of a form; agent-watchdog link or install
fixes it.
Pointing it at another file. Set AGENT_WATCHDOG_STATUS_FILE to read a
status file elsewhere, for example one you wrote by hand or one a hand-run
daemon writes with --status-file:
AGENT_WATCHDOG_STATUS_FILE=/tmp/wd-status.json apps/menubar/.build/release/agent-watchdog-menubar
~ in the value is expanded.
Quitting and relaunching. Quit from More in the popover’s footer. When the app was installed
with install --menubar-bin, launchd does not restart it (KeepAlive is off),
so it stays quit until your next login. Relaunch it with:
launchctl kickstart -k gui/$(id -u)/com.wholeclove.agent-watchdog-menubar
or just run the binary again. Relaunch after a rebuild the same way.
Permissions. The app needs no macOS permissions. It draws a status item,
reads and writes files under your home directory, and runs launchctl,
cmux, the daemon CLI (config schema and config validate --json, for the
settings window), and (for the hidden-item warning) osascript as your user.
It does not use the notification framework itself, Accessibility, or screen recording,
and the window-server query for its own status item needs no permission.
Troubleshooting: the icon is missing on a notched MacBook. macOS lays
status items out from right to left, so the newest item lands closest to the
notch, and when the bar is full it is parked under the notch with no warning of
its own. The app is running; there is simply no room. Third-party items cannot
be dragged off the bar, only reordered with Command-drag, and reordering can
push a different item under the notch instead. The app’s item needs about 37
pt of free bar beside the notch. On the machine this was diagnosed on, the bar
had left only a 29 pt gap, so freeing a slot was the only fix: quit another
menu bar app, or use a menu bar manager. The app notices when it is hidden and
warns once (see “Hidden-item warning”). Confirm it is alive with
launchctl print gui/$(id -u)/com.wholeclove.agent-watchdog-menubar or
pgrep -fl agent-watchdog-menubar, and look for the status item is hidden
line in ~/Library/Logs/agent-watchdog/menubar.stderr.log.
Hidden-item warning
After every refresh the app asks the window server whether its status item is on screen. Once per transition from visible (or never seen, as at launch) to hidden it:
- writes one line to stderr (
menubar.stderr.logunder launchd),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, with the free-a-slot fix in the body; - 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 the 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 a reading the window server has not laid out yet (zero width, as on the first refresh after launch) decides nothing.
Troubleshooting
The menu bar app says the daemon is not running, or the icon is eye.slash.
The status file is missing or older than 2.5 poll intervals. Check whether the
agent is loaded and whether it is crash-looping:
launchctl print gui/$(id -u)/com.wholeclove.agent-watchdog | head -30
tail -50 ~/Library/Logs/agent-watchdog/stderr.log
A poll failed line explains a stale file. A status file write failed line
means the status path is not writable. For a from-source install, if
launchctl print shows a non-zero last exit status and the log is empty, the
node path baked into the plist may be gone: install records the exact
node binary that ran it, which under nvm is version-specific, so removing
that Node version after an upgrade breaks the agent. Run install again from
the new Node. (A downloaded install has no such path baked in — its plist
runs the installed agent-watchdog binary directly, so this does not apply;
see “Download a prebuilt build”.) If the app shows
Daemon stopped at ... while the agent is loaded, a long-running hand watch
(without --once) was stopped after writing the default status file; the
installed daemon overwrites it on its next poll. Give hand runs
--no-status-file or their own --status-file. A watch --once run never
causes this.
The daemon seems stuck after an upgrade. An install from an earlier
release may still carry ProcessType Background, which lets macOS throttle
the daemon’s disk reads so hard that it never writes a first status while
Spotlight is busy. Run agent-watchdog install again: it rewrites the plist
with ProcessType Standard and reloads the agent. To check which class the
loaded agent runs under:
launchctl print gui/$(id -u)/com.wholeclove.agent-watchdog | grep -i processtype
install ends with ... is not loaded and exit code 1. install verifies
the job with launchctl print after loading it, so this means launchd refused
or dropped the job, usually because a bootout of the previous instance was
still in flight. Ask launchd for its own account of the service, then re-run
install once it has settled:
launchctl print gui/$(id -u)/com.wholeclove.agent-watchdog
When print reports the service as missing, running the bootstrap by hand
shows launchd’s own error:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.wholeclove.agent-watchdog.plist
An install that printed loaded via ... and exited 0 did leave a job behind.
No sessions found. status prints No active sessions found. when the
store has no live entries and the transcript scan finds nothing modified within
--stale-after. Check:
~/.cmuxterm/claude-hook-sessions.jsonexists and lists your session. It is written by cmux’s Claude Code hooks, so sessions started outside cmux, or before the hooks were installed, appear only through the transcript scan (no surface for the menu bar to focus, lifecycleunknown).- You did not pass
--no-scan-transcripts, a--sessionprefix, or a--cwdthat excludes everything. - The session has had activity within
--stale-after(default 6h). Raise it to see older sessions. - Run
agent-watchdog status --verboseto see which transcripts were skipped and why. A store entry whose transcript file is missing is logged atdebuglevel once per session, not on every poll.
Notifications do not appear. The daemon posts every notification through
osascript (display notification). Those appear under the Script Editor
identity, so check System Settings, Notifications, for Script Editor, and make
sure Focus is not silencing them. An osascript notification failed line in
the log means the call itself failed; the tick still completes and the status
file records no notify event for it. Confirm a rule actually fired: with --verbose, each session logs
actions=N per poll, and the hysteresis rule means a threshold fires only once
until it re-arms.
The daemon ignores my config file. Three places tell you why:
agent-watchdog config validateprints the error the daemon hit, with exit code 2 (okmeans the file is fine and the problem is elsewhere).- The menu bar popover’s header reads
Config file ignored: <message>while the daemon runs on flags and defaults; the settings window shows the same message, with the file’s path, in a red banner. configErrorin the status file carries the message, the path, and when the load failed.configSourcesthen shows every setting ascliordefault, andstderr.loghas aconfig file ignored, running on flags and defaultsline from the daemon’s start. Aconfig file ignorednotification was sent once at that start.
If config validate says ok, check that the daemon reads the file you are
editing: configFile.path in the status file names it (a daemon installed
with --config <path> reads that path, and one running under --no-config
reads none, with configFile null). Fix the file, run config validate
again, and restart the daemon; the error clears with the first status write.
To get a hand run going while the file is broken, pass --no-config.
Settings window says a value is set by a flag. The row is disabled with
Set by a command-line flag in the launch agent; reinstall the daemon to manage it here. A plist from an older install still bakes that setting
after watch (install --print, or the plist under ~/Library/LaunchAgents,
shows it), and a flag always wins over the file. Run agent-watchdog install
again: it moves the baked settings into the config file when there is none
yet, or drops them with a notice when the file already exists, then reloads
the daemon. Reopen the window after the restart.
Saved but nothing changed. Settings are read once, at daemon start. After
a save (or a hand edit) the daemon keeps its old values until it is
restarted: the popover shows Restart daemon to apply settings, the settings
window shows an orange banner with a Restart daemon button, and
configFile.changedSinceLoad is true in the status file. Restart from either
of those, or by hand:
launchctl kickstart -k gui/$(id -u)/com.wholeclove.agent-watchdog
Then compare Daemon is running with in the window, or the config summary
under the popover’s daemon state, with what you saved. If it still differs, the setting is locked by a
flag (previous entry) or the file was rejected on load (entry above).
Generate handoff is disabled or refused. Hover the button for the reason.
Session busy: session state is unknown means the daemon has no evidence the
session is idle: a Codex session outside cmux, or a Claude Code session that
claude agents does not list. the session is mid-turn clears when the turn
ends. A reason naming the command-line tool means the menu bar could not run
the harness CLI: set openai-codex-path in Settings for Codex, or install
Claude Code where PATH or ~/.local/bin finds it. Still running or unknown
clears once the daemon’s journal settles the earlier request. This daemon does not report handoff generation means the daemon is older than the menu
bar app; restart or reinstall it.
Percentages look wrong. The window is an estimate. A session above 100%
means the real window is larger than the built-in table assumes. Add
--model-window <model>=<tokens> for the model shown by status.
Which logs to check.
| File | Contains |
|---|---|
~/Library/Logs/agent-watchdog/stdout.log |
info and debug lines: startup config, per-session debug lines, re-arm notices, dry-run actions. |
~/Library/Logs/agent-watchdog/stderr.log |
warn and error lines: every notification, plus poll and write failures. |
~/Library/Logs/agent-watchdog/menubar.stderr.log |
Menu bar app diagnostics: the status path it watches, every launchctl or cmux command it ran, and the status item is hidden and visible again lines. |
The log files are not rotated; truncate them when they grow.
Resetting alert state. Alert state lives in
~/.local/state/agent-watchdog/state.json (--state-file). Because thresholds
fire once per crossing, a session that already alerted will not alert again
after a restart. To re-alert, stop the daemon, delete the file, and start it
again:
launchctl bootout gui/$(id -u)/com.wholeclove.agent-watchdog
rm ~/.local/state/agent-watchdog/state.json
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.wholeclove.agent-watchdog.plist
For a one-off experiment, point a hand run at a fresh file instead:
--state-file /tmp/wd-fresh.json.
Selecting Claude Code and Codex
Both harnesses are enabled by default. To monitor Codex alone:
agent-watchdog status --harnesses codex
agent-watchdog watch --once --dry-run --harnesses codex \
--state-file /tmp/agent-watchdog-codex-preview.json
The equivalent configuration is "harnesses": ["codex"]. Use
--session codex:<prefix> for a harness-qualified session filter. Codex reads
its own data root and window evidence; the legacy context-window, model-window
and cache-ttl settings remain Claude-specific. New scoped Codex settings appear
in the menu bar settings window through the generated settings schema.
Unavailable context or cache data is shown explicitly and does not trigger
threshold actions. Codex cache expiry is currently unavailable. See the daemon’s
reference in apps/watchdog/README.md#codex-sessions-and-unavailable-metrics
for details.