Claude Code

Get a beep when Claude Code needs input, asks for permission, finishes, or fails. BirdyBeep wires into Claude Code's hook system — and once installed, every Claude Code session on this machine appears in the app automatically.

~2 min setup
user-level config
open source

Quick install

If this machine is already paired (pair machine guide), one command does everything:

birdybeep agent install claude

It patches your Claude Code settings non-destructively — backing up the original first and adding only BirdyBeep-managed entries. birdybeep agent install all does the same for every harness it detects.

Sessions sync

Sessions sync event-first: a session shows up the moment it emits its next lifecycle event after install — start, resume, input, approval, idle, finish, or fail. There is no background daemon and nothing polling your terminal; if Claude Code emits nothing, nothing is sent.

What gets written

Install adds these BirdyBeep-managed hook entries to ~/.claude/settings.json (your existing hooks are preserved):

~/.claude/settings.json

{
  "hooks": {
    "SessionStart":      [{ "matcher": "", "hooks": [{ "type": "command", "command": "birdybeep hook claude", "timeout": 10 }] }],
    "Notification":      [{ "matcher": "", "hooks": [{ "type": "command", "command": "birdybeep hook claude", "timeout": 10 }] }],
    "PermissionRequest": [{ "matcher": "", "hooks": [{ "type": "command", "command": "birdybeep hook claude", "timeout": 10 }] }],
    "Stop":              [{ "matcher": "", "hooks": [{ "type": "command", "command": "birdybeep hook claude", "timeout": 10 }] }],
    "StopFailure":       [{ "matcher": "", "hooks": [{ "type": "command", "command": "birdybeep hook claude", "timeout": 10 }] }],
    "SubagentStop":      [{ "matcher": "", "hooks": [{ "type": "command", "command": "birdybeep hook claude", "timeout": 10 }] }]
  }
}

Each hook calls birdybeep hook claude with a 10-second timeout so a slow or offline send never blocks Claude Code. No token is written here — the command reads your machine token from the secure store at event time. Claude Code reads settings live, so no restart is needed.

Events you'll get

claude event	beep type	example push
SessionStart	session_started · session_resumed	silent — the session appears in the app
Notification {permission_prompt}	approval_required	claude needs your approval
Notification {idle_prompt}	agent_idle	claude is waiting
Notification {other}	needs_input	claude needs your input
PermissionRequest	approval_required	claude needs your approval
Stop	agent_completed	claude finished
StopFailure	agent_failed	claude hit an error
SubagentStop	subagent_completed	silent — tracked in the session

With Private Mode on (free for everyone), the push drops the repo, branch, path, and command and just says “an agent needs you.”

Test it

Send a real test beep to confirm pairing, hooks, and push delivery end to end:

birdybeep test
# → beep sent. check your phone.

Not chirping? Run birdybeep doctor — it checks pairing, hook config, and push delivery, and points at the fix.

Security note

security note

Your machine token lives in the OS keychain (or ~/.config/birdybeep/ with strict permissions), is never written into repos or harness config files, and can be revoked or rotated from the app at any time. Notification bodies are never stored on our servers, and absolute paths are hashed or redacted. All adapter source is public under MIT — read it on github.