IdlePal for Codex.

IdlePal for Codex adds five hooks to ~/.codex/hooks.json. Codex runs a new hook only after you trust it, so setup ends with one visit to /hooks. After that Pip wakes when you send Codex a prompt, flags permission requests, and tucks away when Codex stops, is interrupted or ends the session.

Signals from Codex: started, finished and needs you. Nothing else leaves the hook.

Set up IdlePal for Codex

Install IdlePal from the Mac App Store.
Coming this winter for macOS 14 or later. Leave your email at the bottom of this page.
Run in Terminal.
curl -fsSL https://raw.githubusercontent.com/initiums/idlepal-integrations/main/codex/install.sh | shAt launch
Trust the hooks in Codex.
/hooks
That's it.
Codex runs a new hook only after you trust it once. Open /hooks and approve the IdlePal entries.

Five Codex events, three signals

Each Codex event runs open -g "idlepal://…" on your Mac with one signal and a session ID. Nothing goes over the network, and the hook never reads your prompts, code or output.

Codex hook events and the signal IdlePal receives for each
Codex event	IdlePal hears	What happens
`UserPromptSubmit`	started	You sent Codex a prompt. The panel drops from the notch without taking your keyboard.
`PermissionRequest`	needs you	Codex wants approval to run something. If the panel is open, an orange banner appears. It never opens the panel just for this.
`Stop`	finished	Codex finished its turn. If you never clicked the panel, it closes.
`Interrupt`	finished	You stopped Codex mid-run, so the session doesn't stay marked as working.
`SessionEnd`	finished	The Codex session ended.

Where the Codex hooks live

~/.codex/hooks.json: Five hook groups are added, one per event above, with a 5 second timeout (1 second for Interrupt and SessionEnd). Your other hooks are kept.
~/.codex/hooks.json.bak-idlepal: A copy of your file from before the change, written on every install and uninstall.
~/.codex/hooks/idlepal-signal.sh: The script the hooks run. It reads only the session_id from Codex's hook input, runs open -g "idlepal://…" and always exits 0.

Codex hooks are new, and their format has changed before. If a Codex update stops Pip waking up, run the install command again: it replaces the IdlePal entries in place.

Interrupts and several Codex sessions

Codex is the one agent where IdlePal hears interrupts. Stop a run and the Interrupt hook sends finished straight away, so Pip doesn't sit awake waiting for a Stop that never comes. Each Codex session sends its own session_id, so two terminals count as two agents and the panel stays down until the last one is done.

Remove the hooks

curl -fsSL https://raw.githubusercontent.com/initiums/idlepal-integrations/main/codex/install.sh | sh -s uninstallAt launch

IdlePal keeps working without it: press ⌥⌘G or click the menu bar icon and Pip is there.

If Pip doesn't wake up for Codex

Codex skips hooks you haven't trusted. Run /hooks and approve the IdlePal entries.
Open IdlePal's Settings → AI agents. If Codex says "Not connected yet", no hook has fired: restart Codex and send a prompt.
Check "Open when an agent starts working" is on in IdlePal's settings.
Open ~/.codex/hooks.json and check for entries that mention idlepal-signal.sh. If the file isn't valid JSON, the installer left it unchanged.
Codex running on another machine over SSH runs its hooks there, where they can't reach the app on your Mac.

Also: IdlePal for Claude Code · IdlePal for Cursor

Questions about IdlePal for Codex

Why does Codex ask me to trust the IdlePal hooks?

Codex doesn't run a new hook until you approve it. Open /hooks in Codex once after installing and approve the IdlePal entries. Until you do, Codex skips them and Pip stays asleep.

Does IdlePal tell me when Codex needs permission?

Yes, if the panel is open. Codex's PermissionRequest hook sends needs you, and IdlePal shows an orange banner. If the panel is closed, IdlePal leaves it closed.

What happens in IdlePal when I interrupt Codex?

The Interrupt hook sends finished right away, so the panel tucks away (or shows a banner if you were playing) instead of waiting for the next prompt.

Does IdlePal for Codex read my prompts or code?

No. The hook reads Codex's input only to find the session_id, then runs open -g on your Mac. Nothing is sent over the network, and IdlePal never sees prompts, files or output.

Get Pip first.

One email when IdlePal is on the Mac App Store. Nothing else.

Buttondown opens in a new tab to confirm. Unsubscribe any time.

macOS 14 or later. Best on a MacBook with a notch.