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. A fresh install uses notifications only. Existing explicit messaging settings are preserved on upgrade; installation does not reset your preferences.

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 a session in the menu to focus its terminal; use 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, including explicit action selections. Review Agent messages before enabling handoffs. 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. 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.