agent-watchdog
Keep track of your coding agents’ context without checking every terminal. agent-watchdog monitors Claude Code and Codex sessions in cmux, computes context usage and prompt-cache expiry from each session’s transcript and cmux’s session store, alerts you through macOS notifications as context usage rises, and shows session status in an optional macOS menu bar app.
Claude sessions support estimated prompt-cache expiry alerts; Codex cache expiry is currently unavailable.
The menu bar can also show plan usage, with separate provider controls and configurable alerts in Settings. Codex supports fresh allowance reads; Claude’s status-line bridge displays historical usage with unknown age and cannot yet send usage alerts. Usage monitoring follows the enabled harnesses by default, with separate opt-outs in Settings.
Older Codex rollout files are discovered progressively across daemon polls; one-shot commands scan only the first bounded page. See Codex parity details.
Prerequisites
For the prebuilt download, use an Apple silicon Mac running macOS 13 or newer, with cmux and Claude Code or Codex. Node, Yarn, and Swift are not required.
To build from source, you also need Node 26 and the repository’s vendored Yarn 4. The optional menu bar app needs the Xcode command line tools with Swift 5.9
or later and macOS 13 or newer. Run nvm use to select the repository’s Node
version. If yarn is not on your PATH, use
node .yarn/releases/yarn-4.11.0.cjs in its place.
Download a prebuilt build
Download and install the daemon and menu bar app:
curl -fsSL https://agent-watchdog-downloads.s3.us-east-2.amazonaws.com/agent-watchdog-darwin-arm64.tar.gz | tar -xz
./agent-watchdog/install.sh
The installer copies the app to ~/.local/share/agent-watchdog, links its
commands into ~/.local/bin, and starts both background services. Add
~/.local/bin to your PATH if needed, then run agent-watchdog status to see
discovered sessions.
See the download page for build details and checksums, or the usage guide for installer options and upgrades. To build from a clone, follow the quick start below.
Quick start
git clone git@github.com:Wholeclove/agent-watchdog.git
cd agent-watchdog
nvm use
yarn install
yarn build
Try it against your real cmux sessions before installing anything:
node apps/watchdog/dist/bin/agent-watchdog.js status
Symlink the built binary into ~/.local/bin, then run it directly
(make sure ~/.local/bin is on your PATH):
yarn workspace @agent-watchdog/watchdog start link
agent-watchdog watch --once --dry-run --state-file /tmp/agent-watchdog-preview.json
Install it as a background daemon (launchd agent, logs under
~/Library/Logs/agent-watchdog/):
agent-watchdog install
Settings live in ~/.config/agent-watchdog/config.json, not in the
launch agent. Any settings flag you pass to install is written into
that file; later, edit the file (or use the menu bar app’s settings
window) and restart the daemon, with no reinstall:
agent-watchdog config validate
launchctl kickstart -k gui/$(id -u)/com.wholeclove.agent-watchdog
Want the menu bar app too? Build it and pass its binary to install
(or link during development):
yarn workspace @agent-watchdog/menubar build
agent-watchdog install --menubar-bin apps/menubar/.build/release/agent-watchdog-menubar
For the step-by-step walkthrough of all of the above, the config file,
every flag, the alert rules, and the menu bar app, see docs/usage.md.
See apps/watchdog/README.md for the full command and flag reference
(watch, status, install/uninstall, link, config, and every
threshold and notification flag).
Features
- Context alerts: notifications at 35% and 75% usage by default, with configurable thresholds for your workflow.
- Claude cache alerts: an estimated expiry time and a notification when an idle session’s cache is about to expire. Codex cache expiry is unavailable.
- Session status: context usage in a CLI status table and a JSON status file for integrations.
- Menu bar popover: plan allowances, each session’s context, cache, and handoff, and today’s locally observed token activity per session and subagent family. Focus a session in cmux, generate or open a handoff for an idle session, manage the daemon, and edit settings. Activity totals are local tokens, not plan usage or cost.
Both Claude Code and Codex are monitored by default. See Selecting Claude Code and Codex for filters and differences between the two.
Repo layout
apps/watchdog— the daemon (@agent-watchdog/watchdog). See its ownREADME.mdfor CLI and flag details.apps/menubar— the menu bar app (@agent-watchdog/menubar), a Swift Package Manager project. Reads the status file the daemon writes; it does not compute anything itself.apps/site— the docs and download site (@agent-watchdog/site), an Astro static site outside thetsc -bgraph like the menu bar app. It renders this repo’s own markdown in place; see its ownREADME.md.packages/eslint-config— shared lint presets (@agent-watchdog/eslint-config).tsconfig/— shared TypeScript presets (base/lib/spec).docs/— repo-level notes; seedocs/README.md.
Development commands
Run from the monorepo root:
yarn build # tsc -b tsconfig.json (apps/watchdog only — apps/menubar (Swift) and apps/site (Astro) build separately)
yarn typecheck # per-workspace typecheck
yarn lint # per-workspace eslint
yarn test # per-workspace jest / swift test
yarn format # prettier --write .
yarn format:check
Or scope any of these to one workspace: yarn workspace @agent-watchdog/watchdog <script>,
yarn workspace @agent-watchdog/menubar <script> (shells out to
swift build / swift test, and no-ops on non-macOS), or
yarn workspace @agent-watchdog/site <script> (Astro; see
apps/site/README.md).
GitHub Actions is currently disabled on this repo (an org billing
issue, not a repo decision) — .github/workflows/ci.yml is unused for
now, so the commands above are the actual gate before pushing.
Agent tooling
This repo ships Claude Code skills under .claude/skills/ — agent-triggered
guidance for the day-to-day workflow, not slash commands:
- change-control — branch/PR/merge rules, why CI is currently disabled and what the local gate is instead, non-negotiable engineering rules.
- conventional-commit — commit message format and scopes for this repo.
- validation-and-qa — which test suite covers a change and what counts as evidence.
- wip-to-pr — turning uncommitted working-tree changes into a branch, commits, and a PR.
- workspace-docs — the generator behind the workspace command reference (below).
- write-skill — authoring or improving a skill.
Workspace-docs generator. .claude/scripts/generate-workspace-docs.js
(zero dependencies) reads every workspace’s package.json scripts and
writes .claude-context/generated-workspace-commands.md — a gitignored
command reference, regenerated by a SessionStart hook
(.claude/settings.json) at the start of every agent session. Root
CLAUDE.md pulls it in via
@.claude-context/generated-workspace-commands.md.