Taphaptic

Taphaptic

Taphaptic sends Claude Code and Codex lifecycle notifications to an independent
Apple Watch app.

Architecture

- Claude Code and Codex hooks run a small taphapticctl adapter on the user's Mac.
- The adapter sends a minimal, provider-neutral event to the HTTPS relay.
- The relay sends a standard alert directly to the watch-only app through APNs.
- A local Bonjour/HTTP mode remains available for development and self-hosting.

Prompts, transcripts, repository files, tool arguments, and generated answers
are not sent by the built-in hooks.

Requirements

- macOS with Go 1.22+ for building the Mac adapter
- Xcode 26+ with the watchOS 26 platform installed for App Store builds
- Apple Watch running watchOS 11 or later
- A relay URL for background notifications

Connect Claude Code, Codex, or both

Build/start a local relay for development:

Install both adapters and print a watch pairing code:

Provider-specific alternatives:

For a hosted relay:

Codex requires review of new command hooks. Open /hooks in Codex and trust the
Taphaptic entries after inspecting them. Taphaptic never bypasses hook trust.

Apple Watch setup

1. Install and launch Taphaptic on Apple Watch.
2. Enter the four-digit code printed by the Mac setup command.
3. Allow notifications when prompted.
4. Open Settings in Taphaptic and choose Send test notification.

The hosted/APNs path works when Taphaptic is not open. The local HTTP fallback
polls only while the watch app is active.

Relay configuration

The container listens on PORT and persists state under TAPHAPTIC_DATA_DIR.
Production APNs requires:

Set TAPHAPTIC_TRUST_PROXY_HEADERS=true only when the service is behind a
trusted reverse proxy that overwrites X-Forwarded-For.

Never put the APNs private key in the repository, image, watch…