WatchCode CLI

Send Claude Code notifications directly to your Apple Watch.

What is WatchCode?

WatchCode lets you receive notifications from Claude Code on your Apple Watch - no iPhone required. Get instant alerts for permission requests, tool usage, errors, and more.

Installation

# Install pipx if you don't have it
brew install pipx && pipx ensurepath

# Install WatchCode CLI
pipx install watchcode-cli

Quick Start

1. Install the WatchCode app on your Apple Watch (available on the App Store)

2. Get your setup code from the Watch app:

   • Open WatchCode on your Watch
   • Go to Settings
   • Note your setup code (format: XXXX-XXXX-XXXX)

3. Configure the CLI:

   watchcode setup
   

   This will:

   • Prompt for your setup code
   • Install Claude Code hooks automatically
   • Send a test notification to verify setup

4. Done! Claude Code will now send notifications to your Watch.

Commands

watchcode setup

Interactive setup wizard. Configures WatchCode with your setup code, installs hooks, and sends a test notification.

watchcode setup

watchcode test

Send a test notification to your Watch.

watchcode test

watchcode status

Show configuration and hook status.

watchcode status

watchcode install-hooks

Install Claude Code hooks for WatchCode (normally done during setup).

watchcode install-hooks

watchcode uninstall-hooks

Remove WatchCode hooks from Claude Code.

watchcode uninstall-hooks

watchcode flush

Manually send queued offline notifications.

watchcode flush

watchcode notify

Send notification from Claude Code hook (used internally by hooks).

# Examples (normally called by Claude Code hooks)
watchcode notify --event stop
watchcode notify --event permission_request --requires-action
watchcode notify --event notification

How It Works

WatchCode uses Claude Code's hook system to send notifications:

1. Hook triggers - Claude Code calls WatchCode hooks on events (permission requests, tool usage, etc.)
2. Relay server - WatchCode CLI sends notification to Cloudflare Worker relay
3. APNs delivery - Relay forwards to Apple Push Notification service
4. Watch receives - Your Apple Watch receives the notification instantly

Supported Events

WatchCode supports all Claude Code hook types:

• Stop - When Claude Code stops execution
• PreToolUse - Before using a tool (optional confirmation)
• PermissionRequest - When Claude needs permission (requires action)
• Notification - General notifications
• SessionStart / SessionEnd - Session lifecycle events

Offline Queue

If the relay server is unreachable, notifications are queued locally and automatically sent when connectivity is restored.

View queued notifications:

watchcode status

Manually flush queue:

watchcode flush

Configuration

WatchCode stores configuration in ~/.watchcode/:

• config.json - Setup code and relay URL
• offline_queue.json - Queued notifications (when offline)

Claude Code hooks are installed in ~/.claude/settings.json.

Privacy & Security

• No data collection - WatchCode only sends what's needed for notifications
• Secure relay - End-to-end encrypted via APNs
• Auth tokens - Setup codes authenticate your device (no passwords)
• Open source - Full source code available on GitHub

Troubleshooting

Notifications not appearing on Watch

1. Check configuration: watchcode status
2. Verify hooks are installed: watchcode install-hooks
3. Test notification: watchcode test
4. Check Watch is connected and WatchCode app is installed

Network errors

If you see "Network error: Notification queued", the relay server is unreachable. Notifications will be queued and sent automatically when online. Run watchcode flush to retry manually.

Invalid setup code

Setup codes are 12 alphanumeric characters (format: XXXX-XXXX-XXXX). Get your code from the WatchCode app on your Watch (Settings screen).

Links

• GitHub: https://github.com/egor-gm/WatchCode
• Issues: https://github.com/egor-gm/WatchCode/issues
• Watch App: Available on the App Store

License

MIT License - see LICENSE file for details.