Skip to content
agent-watchdog

Install

Requirements

The prebuilt package needs an Apple silicon Mac running macOS 13 or newer, cmux, and Claude Code or Codex. It includes its runtime. For Intel Macs or development, use the source build instructions.

Install the download

Open the download page for the current package, checksum, and installation command. Extract the package and run ./agent-watchdog/install.sh. It installs the daemon and menu bar app for your user account. The daemon notifies you; it never types into an agent’s terminal. Existing explicit settings are preserved on upgrade; installation does not reset your preferences.

Set up subscription usage

Install Codex and/or Claude Code and sign in with your subscription account before running the installer. Installation configures usage monitoring for each enabled provider:

  • Codex: finds the executable on your shell’s PATH, in standard install locations, or in the Codex app. It saves the detected path and preserves an install-time CODEX_HOME, so the background service uses the same account. Existing explicit paths and disabled monitoring settings are kept.
  • Claude: configures the status-line bridge in ~/.claude/settings.json (or the absolute CLAUDE_CONFIG_DIR used during installation). An existing status-line command keeps rendering through the bridge. The original is recorded beside settings in settings.agent-watchdog-statusline.json for reinstall and uninstall. Existing account bindings and usage history are kept.

Then open a signed-in Claude Code session so it emits its first usage sample. Claude Code 2.1.251 or newer and a subscription account are required for the supported rate-limit fields. Codex usage is collected in the background. The installer does not install the provider tools or sign you in. If a tool is missing, finish its setup and rerun the watchdog installer.

Codex discovery skips cmux’s temporary terminal shims and follows PATH to the actual executable. If cmux uses CMUX_CUSTOM_CODEX_PATH, that executable is preferred when it exists and is not itself a cmux wrapper. An existing explicit openai-codex-path is preserved; correct it in Settings if it names a wrapper.

For an existing watchdog installation, rerun agent-watchdog install to add the usage wiring. Keep your existing --config argument if you use a custom file. Preview the changes with agent-watchdog install --print. To manage provider setup yourself, use agent-watchdog install --no-setup-usage, or pass the flag through the download installer:

./agent-watchdog/install.sh -- --no-setup-usage

Malformed, symlinked, or explicitly disabled Claude status-line settings are left unchanged with a setup notice. Existing manual bridges are also kept. Project-level Claude settings can override the user status line; see the manual bridge instructions for custom renderers or overrides. After switching Claude accounts, run agent-watchdog usage-bridge bind 'Claude account' to discard the old readings.

Claude usage comes from Claude Code’s own usage command, which needs Claude Code signed in on this machine; the bridge is its fallback, and only fresh usage-command readings send Claude allowance alerts. If either card still says Unavailable, follow subscription usage troubleshooting.

Check the installation

agent-watchdog status

Expect a session table and the watchdog icon in the macOS menu bar. Open a Claude Code or Codex session in cmux if the table is empty. Click the icon to open the popover: a session’s Focus button brings up its terminal, and the gear opens Settings to configure alerts. If the command is missing, add ~/.local/bin to PATH or run ~/.local/bin/agent-watchdog status. See Troubleshoot if sessions still do not appear.

Upgrade

Download and extract the new package, then run its install.sh again. The installer replaces the installed binaries and restarts the background services. Your config file is kept and migrated. Settings that an older build accepted but this one no longer has are dropped silently. Run agent-watchdog status after upgrading.

Uninstall

agent-watchdog uninstall

This stops and removes the daemon and menu bar launch agents. It keeps your config at ~/.config/agent-watchdog/config.json. If installation configured Claude’s status line, uninstall restores its previous command unless you have replaced it since then. Use the same CLAUDE_CONFIG_DIR for uninstall if you used a custom directory for setup. It also leaves the installed package (~/.local/share/agent-watchdog by default), links in ~/.local/bin, logs in ~/Library/Logs/agent-watchdog, and state in ~/.local/state/agent-watchdog. Remove those manually if you want a full reset; check custom install paths first. Handoff files in repositories are kept.