Codex

BirdyBeep wires into Codex with its notify program plus lifecycle hooks, so you get a beep when a turn completes or Codex needs you — and sessions on this machine appear in the app automatically.

~2 min setup
one-time trust
open source

Quick install

If this machine is already paired, one command configures Codex:

birdybeep agent install codex

One-time trust

Codex skips hooks it hasn't trusted. After install, open Codex and run /hooks once to grant trust. Until the first event lands, the app shows this integration as needs trust; after that, Codex sessions on this machine are tracked automatically. The notify program (turn-complete) works without the trust step.

What gets written

Install adds these BirdyBeep-managed entries to ~/.codex/config.toml (your existing config is preserved):

~/.codex/config.toml

# ~/.codex/config.toml  (birdybeep-managed entries)
notify = ["birdybeep", "hook", "codex"]

[hooks]
SessionStart      = ["birdybeep", "hook", "codex"]
PermissionRequest = ["birdybeep", "hook", "codex"]
PostToolUse       = ["birdybeep", "hook", "codex"]
SubagentStart     = ["birdybeep", "hook", "codex"]
SubagentStop      = ["birdybeep", "hook", "codex"]

No token is written — the command reads your machine token from the secure store at event time. Stop is intentionally not registered because notify already covers turn-complete.

Events you'll get

codex event	beep type	example push
turn complete (notify)	agent_completed	codex finished
SessionStart	session_started	silent — the session appears in the app
PermissionRequest	approval_required	codex needs your approval
PostToolUse	needs_input	codex needs your input
SubagentStart · SubagentStop	subagent_*	silent — tracked in the session

With Private Mode on (free for everyone), the push drops repo, branch, path, and command.

Test it

Send a real test beep to confirm the integration end to end:

birdybeep test
# → beep sent. check your phone.

Not chirping? birdybeep doctor checks pairing, trust, hook config, and delivery.

Security note

security note

Your machine token lives in the OS keychain (or ~/.config/birdybeep/ with strict permissions), is never written into repos or 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.