Codex

Install BirdyBeep's Codex notify command and hooks to receive notifications when a turn finishes or needs attention. New Codex sessions on this machine appear in the app after their first event.

~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"]

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

If the test beep does not arrive, run birdybeep doctor. It checks pairing, trust, hook configuration, and delivery.

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.