AgentWatch

Apple Watch / Android notifications for Claude Code and AI agent workflows.

AgentWatch lets you walk away from your Mac (or Windows PC) while Claude Code works. When the agent needs your approval, needs attention, or finishes a task — your wrist vibrates with a short event card. Works with Apple Watch, Android phones, and connected bands (Huawei/Xiaomi/Samsung bands that sync phone notifications).

中文用户请查看 README_CN.md

Why AgentWatch?

Claude Code is powerful — but you don't want to watch every command. You only need to know when:

• A real "Allow this bash command?" permission dialog appears
• The agent needs your approval or input
• A task finishes and needs your review
• Something went wrong that requires your attention

The problem: You start a long task, walk away for coffee, come back 20 minutes later and realize Claude Code has been waiting on a permission prompt for 19 of those minutes.

The solution: AgentWatch hooks into Claude Code's event system, filters out the noise, and pushes only truly actionable alerts to your wrist. Your watch vibrates → you glance → you know whether to rush back or stay at the coffee machine.

What separates AgentWatch from other solutions?

Screenshots

(Coming soon via GitHub Releases — screenshots will be added here.)

macOS menu bar app: Status at a glance — Bark OK, hooks installed, persona theme, recent events.

Windows tray app: Right-click for full status, persona switching, test push, task boundaries.

Apple Watch / Android band notification: Title + risk level + suggested action in a compact card format.

Phone notification: Same card syncs to Notification Center.

Features

Core

Desktop Apps

Persona Themes

How It Works

Claude Code hooks           AgentWatch Python CLI
─────────────────         ─────────────────────────
PreToolUse         ──▶     danger / drift detection
PostToolUse        ──▶     failure counting
Notification      ──▶     attention classification
Stop              ──▶     task completion
PermissionRequest ──▶     ✓ PUSH to Watch (reliable)
PermissionDenied  ──▶     log only (no push)
                           │
                           ├── notification policy (actionable by default)
                           ├── persona message builder
                           ├── Bark push ──▶ phone ──▶ Apple Watch / Android band
                           └── logs/agentwatch_events.jsonl

Key design decisions:

• PermissionRequest is the most reliable signal for real "Allow this command?" prompts. It fires exactly when the Claude Code permission dialog appears.
• Notification is a fallback for general attention events.
• Stop handles task completion.
• PreToolUse timeout defaults to log-only — a 4-second gap between PreToolUse and PostToolUse could just be a slow Bash command, not a permission prompt.

Installation Methods

You have three options, from simplest to most advanced:

Option 1 — CLI Only (fastest)

No GUI apps needed. The core functionality (hooks → watch notifications) works entirely via CLI. Install Python, clone the repo, pip install -e ., configure Bark, install hooks. Done. See Quick Start.

This is all you need for notifications to work. The GUI apps are convenience layers.

Option 2 — Download Pre-Built Apps (recommended)

Download, unzip, double-click. No terminal needed.

macOS:

1. Double-click AgentWatch.app (menu bar top-right, no Dock icon)
2. ● AW → Add / Update Bark Key... → paste your Bark key
3. ● AW → Test Push → verify your watch receives it

Windows:

1. Double-click AgentWatchTray.exe (system tray bottom-right)
2. First run picks project directory (auto-remembered)
3. Right-click → Setup Python Environment (auto-prompted if .venv missing)
4. Right-click → Add / Update Bark Key... → paste your Bark key
5. Right-click → Install / Update Claude Code Hooks (one click)

Done. The app and hooks run independently — close the app, notifications still fire.

Option 3 — CLI + Build from Source

Clone the repo and build the desktop apps yourself with a single command (requires Xcode Command Line Tools / .NET 8 SDK).

Quick Start: macOS

Prerequisites

• macOS (Apple Silicon or Intel)
• Python 3.10+
• Claude Code (CLI or VS Code extension)
• iPhone / Android phone with Bark installed

Install

# Clone
git clone https://github.com/dongxutang918-afk/agentwatch.git ~/Projects/agentwatch
cd ~/Projects/agentwatch

# Setup Python environment
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Initialize (creates config and logs directory)
agentwatch init

# Configure Bark key
agentwatch config bark        # paste your Bark URL or key
agentwatch config test        # verify notifications reach your watch

# Install Claude Code hooks (manual, one-time)
bash install_claude_hooks.sh

# Verify
agentwatch doctor             # should show "Status: Ready"

Optional: Build macOS Menu Bar App

bash macos/build_app.sh       # requires Xcode Command Line Tools (swift)
open build/AgentWatch.app     # runs in menu bar, no Dock icon

Double-click alternatives (no terminal needed):

• AgentWatch Setup.command — first-time environment setup
• AgentWatch.command — everyday launcher
• Open AgentWatch App.command — launch the menu bar app

Quick Start: Windows

Prerequisites

• Windows 10/11
• Python 3.10+
• Claude Code (CLI or VS Code extension)
• Phone with Bark installed (iOS/Android)

Install

Recommended (download + run):

1. Download AgentWatch-Windows-x64.zip
2. Unzip anywhere
3. Double-click AgentWatchTray.exe
4. If asked, select your AgentWatch project directory (e.g. C:\Users\dongx\agentwatch)
5. Right-click the tray icon → Setup Python Environment (one-click)
6. Right-click the tray icon → Add / Update Bark Key... → paste your Bark key
7. Right-click the tray icon → Install / Update Claude Code Hooks (one-click)

Done. The tray app shows status, and hooks work independently in the background.

Manual Setup (CLI):

# Clone
git clone https://github.com/dongxutang918-afk/agentwatch.git
cd agentwatch

# Setup
powershell -ExecutionPolicy Bypass -File windows\setup_windows.ps1

# Configure
.\.venv\Scripts\agentwatch.exe config bark
.\.venv\Scripts\agentwatch.exe config test

# Hooks (or use tray menu: "Install / Update Claude Code Hooks")
powershell -ExecutionPolicy Bypass -File windows\install_claude_hooks_windows.ps1

# Verify
.\.venv\Scripts\agentwatch.exe doctor

Optional: Build from Source

# Requires .NET 8 SDK
powershell -ExecutionPolicy Bypass -File windows\build_app.ps1
build\windows\AgentWatchTray\AgentWatchTray.exe

Or double-click Open AgentWatch Windows App.bat.

Bark Setup

AgentWatch sends notifications through Bark, a free open-source push app for iOS and Android.

Step-by-Step

1. Install Bark from the App Store (iOS) or Google Play (Android)

2. Open Bark → the URL at the top shows your key:

   copy

   https://api.day.app/YOUR_KEY/
                          ^^^^^^^^ this is your Bark key
   

3. Copy the full URL or just the key part

4. Paste it into AgentWatch:

   Method	How
   CLI	agentwatch config bark then paste
   macOS menu bar	● AW → Add / Update Bark Key... → paste
   Windows tray	Right-click → Add / Update Bark Key... → paste

5. Test: agentwatch config test (or click "Test Push" in the GUI)

You should receive "AgentWatch Bark 测试" on your phone and wearable device.

Verify Phone & Wearable Sync

• iPhone: Settings → Notifications → Bark → Allow ✅
• Android: Settings → Notifications → Bark → Allow ✅
• Apple Watch: Watch app → Notifications → Mirror iPhone Alerts from Bark ✅
• Android band/watch (Huawei/Xiaomi/Samsung): enable Bark notification sync in your companion app (e.g., Huawei Health, Mi Fitness, Galaxy Wearable)

Claude Code Hooks

Hooks are manual, opt-in — AgentWatch never modifies your Claude Code configuration automatically. A backup of settings.json is always created before modification.

Six hooks are registered:

macOS:

bash install_claude_hooks.sh     # install
bash uninstall_claude_hooks.sh   # remove

Windows:

powershell -ExecutionPolicy Bypass -File windows\install_claude_hooks_windows.ps1
powershell -ExecutionPolicy Bypass -File windows\uninstall_claude_hooks_windows.ps1

⚠️ Upgrade note: If you installed hooks before v0.8.0, re-run the install script to add the two new hooks: PermissionRequest and PermissionDenied. Run agentwatch doctor — it should show Claude hooks: Installed (6/6).

Notification Policy

AgentWatch uses actionable mode by default — only truly interactive events push to your watch.

✅ Pushed to Apple Watch

❌ Logged Only (no watch push)

Switching Modes

To push all events (verbose mode, legacy behavior):

"notification_policy": { "mode": "verbose" }

To enable PreToolUse timeout push (accepts false-positive risk):

"approval_detection": { "timeout_watch_notify": true }

Persona Themes

Switch notification style from the GUI or CLI. No restart needed. Six themes available:

CLI:

agentwatch persona show               # show current theme
agentwatch persona set boss           # switch to 总裁版
agentwatch persona set emperor        # switch to 皇上版
agentwatch persona off                # disable persona
agentwatch persona test permission    # preview (no push)
agentwatch persona test done          # preview (no push)

macOS: ● AW → Persona Theme → choose theme

Windows: Right-click tray icon → Persona Theme → choose theme

Personas only change notification wording — the notification policy (which events push) is unchanged.

macOS Menu Bar App

A native Swift + AppKit app that lives in your menu bar (no Dock icon). Look for ● AW in the top-right.

Build & Launch

bash macos/build_app.sh          # build (requires Xcode CLT: swift)
open build/AgentWatch.app        # launch
# or double-click: Open AgentWatch App.command

Features

Windows Tray App

A native C# / .NET 8 WinForms app that lives in your system tray (bottom-right).

Build & Launch

# Requires .NET 8 SDK
powershell -ExecutionPolicy Bypass -File windows\build_app.ps1
build\windows\AgentWatchTray\AgentWatchTray.exe
# or double-click: Open AgentWatch Windows App.bat

Features

Same as macOS menu bar app, plus:

• Setup Python Environment — one-click .venv setup
• Install / Update Claude Code Hooks — one-click hooks installation (with confirmation)
• Preview Current Persona — see what your notifications will look like without sending a push
• Test Permission Request / Denied — simulate specific hook events

Common Commands

Testing

After setup, verify everything works:

# 1. Health check
agentwatch doctor
# Expected: Status: Ready, Claude hooks: Installed

# 2. Test notification chain
agentwatch config test
# Expected: Notification appears on iPhone / Apple Watch

# 3. Simulate a real permission dialog
agentwatch simulate permission-request
# Expected: Watch notification with your current persona theme

# 4. Simulate task completion
agentwatch simulate done
# Expected: Watch notification "task done"

# 5. These should NOT push (log-only by default):
agentwatch simulate approval-pending    # timeout → log only
agentwatch simulate permission-denied   # deny → log only

Troubleshooting

Phone / watch not vibrating

1. Confirm Bark is installed and working on your phone (send a test from the Bark app itself)
2. Run agentwatch config test — should say "Notification sent"
3. iPhone: Settings → Notifications → Bark → Allow ✅
4. Android: Settings → Notifications → Bark → Allow ✅
5. Apple Watch: Watch app → Notifications → Mirror iPhone Alerts from Bark ✅
6. Android band/watch: enable Bark notification sync in your companion app (Huawei Health, Mi Fitness, Galaxy Wearable, etc.)

Bark returns "device token not found"

• Your Bark key is incorrect or expired
• Open the Bark iOS app → copy the current URL
• Ensure bark_server in config.json is https://api.day.app

"Allow this bash command?" appears but Watch didn't vibrate

1. Run agentwatch doctor — does it say Missing PermissionRequest?
2. If yes, reinstall hooks:
   • macOS: bash install_claude_hooks.sh
   • Windows: powershell -File windows\install_claude_hooks_windows.ps1
3. Test: agentwatch simulate permission-request
4. Restart your Claude Code session — new hooks only take effect in new sessions

Too many false alerts from slow Bash commands

• This is the default — PreToolUse timeouts are log-only (timeout_watch_notify: false)
• Verify config: approval_detection.timeout_watch_notify is false
• Long-running commands (builds, tests) will not trigger watch notifications

macOS app double-click has no window

• It's a menu bar app — look for ● AW in the top-right corner of your screen
• No Dock icon, no window. Click the icon to open the menu.

Windows tray app doesn't start

• Ensure .NET 8 SDK is installed: dotnet --version
• Rebuild: powershell -File windows\build_app.ps1
• Check build\windows\AgentWatchTray\AgentWatchTray.exe exists

Hooks installed but doctor says "Missing"

• Check the Python path in ~/.claude/settings.json points to the correct .venv
• If you moved the project, re-run the install script

Privacy & Security

See SECURITY.md for full details.

Roadmap

• GitHub Release binaries (pre-built .app and .exe)
• Away mode — auto-detect when you step away and enable aggressive monitoring
• Session summary notifications — what was accomplished
• Guard mode — auto-block dangerous operations before execution
• More persona themes
• Pushover / ntfy notification backend support
• Native iOS / watchOS actions (approve/deny from wrist)

License

MIT — see LICENSE.

Contributing

See CONTRIBUTING.md.