Installation

Installation

Requires macOS 14 Sonoma or later · Apple Silicon and Intel (universal binary). No admin rights needed.

Homebrew (recommended)

brew install --cask roypadina/tap/agents-monitor

Newer Homebrew versions may ask you to trust the third-party cask first:

brew tap roypadina/tap
brew trust --cask roypadina/tap/agents-monitor
brew install --cask agents-monitor

The app lands in /Applications/AgentsMonitor.app. Upgrade later with brew upgrade --cask agents-monitor.

Manual install

Download AgentsMonitor.zip from the Releases page, unzip it and drag AgentsMonitor.app into /Applications.

Quarantine and Gatekeeper

Agents Monitor releases are self-signed with a stable identity, so permissions survive updates (not notarized, so first launch still needs Open Anyway) (no paid Apple Developer ID). Homebrew no longer offers --no-quarantine, so the app arrives quarantined, and launching it that way shows a Gatekeeper dialog whose default button is "Move to Trash". Answer it by reflex and the app is deleted from /Applications.

Clear the flag before the first launch:

xattr -dr com.apple.quarantine "/Applications/AgentsMonitor.app"
open /Applications/AgentsMonitor.app

On macOS 15 and later, right-click → Open no longer works: use System Settings → Privacy & Security → Open Anyway. Never click Move to Trash. A copy you build yourself is not prompted.

If the app does vanish, only the bundle is lost. Accounts, settings and alert history live in defaults, so reinstalling restores everything.

First run

1. There is no Dock icon. Look for the gauge icon in the menu bar.
2. Accounts are auto-discovered: ~/.claude and ~/.claude-* (with a matching keychain entry), ~/.codex and ~/.codex-* (with a readable auth.json). See Accounts.
3. macOS asks for notification permission. Allow it for desktop alerts. ntfy and toast alerts work without it.
4. Polling starts immediately. Cards fill in as each account's first poll completes.

Build from source

git clone https://github.com/roypadina/AgentsMonitor.git
cd AgentsMonitor
swift test --package-path AgentsMonitorKit   # optional: logic tests, no network or keychain needed
xcodebuild -workspace AgentsMonitor.xcworkspace -scheme AgentsMonitor \
  -configuration Release -derivedDataPath build build
cp -R build/Build/Products/Release/AgentsMonitor.app /Applications/
open /Applications/AgentsMonitor.app

All logic lives in the local AgentsMonitorKit Swift package. The app target is a thin SwiftUI MenuBarExtra. A local build is signed ad hoc unless you set your own identity, so its signature changes on every rebuild, so Gatekeeper and keychain "Always Allow" choices can reset after each build.

Updating

• Homebrew: brew upgrade --cask agents-monitor
• Manual or source: repeat the install steps. Settings and accounts live outside the app bundle.

Uninstall

brew uninstall --cask agents-monitor     # or: rm -rf /Applications/AgentsMonitor.app
defaults delete com.roy.agentsmonitor    # optional: forget settings and accounts
rm -rf ~/Library/Application\ Support/AgentsMonitor   # optional: usage history behind the graphs

Also remove it from System Settings → General → Login Items if you enabled Start at login.

Remote accounts keep credentials in keychain items named AgentsMonitor-account-<uuid>, which defaults delete does not remove:

security delete-generic-password -s "AgentsMonitor-account-<uuid>"

Uninstalling never touches Claude Code's keychain items or any Codex auth.json.