squawk

https://github.com/user-attachments/assets/e99fe0b1-1423-4f97-bf2a-b0fd287f4eb5

squawk

squawk brings smart macOS notifications to Claude Code. It only alerts you
when Claude is out of sight, offering quick actions to reply, approve, or jump
to the pane.

Features

- Context-Aware Alerts: Silent when focused, in-pane banners when visible,
  and notifications when off-screen.
- Inline Replies: Reply from the notification to keep Claude going.
- One-Click Approvals: Allow permission prompts straight from the alert.
- Message Previews: See Claude's latest response at a glance.
- Smart Lifecycle: Alerts persist until addressed, but auto-clear when you
  focus the pane.
- Clean Grouping: Session notifications update in place instead of
  cluttering your screen.
- Zero-Config: Works out of the box, with optional env var overrides (see
  Configuration).

Events

squawk uses Claude Code hooks to notify on the following events:

Requirements

- Claude Code, tmux, jq, and alerter (Core dependencies)
- Claude for Desktop _(Optional)_ squawk borrows its app icon to make
  notifications look native. Without it, you get a default fallback icon (or you
  can manually set SQUAWK_ICON).

Install

Keep the clone where it is as squawk install symlinks to it and reads it at
runtime (so git pull upgrades in place). squawk install:

1. Checks if required dependencies are correctly installed.
2. Symlinks squawk into ~/.local/bin (override with PREFIX=).
3. Merges its hooks (Stop, StopFailure, Notification, PermissionRequest)
   into ~/.claude/settings.json.
4. Offers to add the tmux snippet the in-pane banner needs to ~/.tmux.conf (or
   prints it for you to add yourself).
Restart Claude Code after installing so it loads the new hooks.

Configuration

All via environment variables (or an…