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

An existing Claude Code session appears after its next event, such as a start, resume, input request, approval request, idle state, completion, or failure. BirdyBeep does not poll or watch your terminal.

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 does not block Claude Code. The command reads your machine token from the secure store at event time and does not write it here. 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.

If the test beep does not arrive, run birdybeep doctor. It checks pairing, hook configuration, and push delivery, then identifies the failed step.

Security note

security note

BirdyBeep reads the machine token from your OS keychain or from ~/.config/birdybeep/ with restricted permissions. It does not write the token to repositories or coding-agent configuration files. You can revoke or rotate it in the app. BirdyBeep does not store notification bodies and hashes or redacts absolute paths. The adapter source is MIT-licensed on GitHub.