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 absoluteCLAUDE_CONFIG_DIRused during installation). An existing status-line command keeps rendering through the bridge. The original is recorded beside settings insettings.agent-watchdog-statusline.jsonfor 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.