Skip to content
agent-watchdog

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 own README.md for 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 the tsc -b graph like the menu bar app. It renders this repo’s own markdown in place; see its own README.md.
  • packages/eslint-config — shared lint presets (@agent-watchdog/eslint-config).
  • tsconfig/ — shared TypeScript presets (base/lib/spec).
  • docs/ — repo-level notes; see docs/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.