Codex Native Notify

简体中文

Dependency-free native macOS and iPhone notifications for Codex CLI.

Codex Native Notify tells you when a Codex turn finishes or pauses for approval. It uses only macOS osascript and Reminders: no app installation, package manager, background daemon, webhook, or third-party push service.

This is an independent community project. It is not affiliated with or endorsed by OpenAI or Apple.

Preview

Task completed	Approval required

What it does

Codex CLI
├── PermissionRequest ──> Mac notification now
│                     └─> iCloud Reminder for iPhone after n seconds (configurable)
└── Stop ───────────────> Mac notification now
                      └─> iCloud Reminder for iPhone after n seconds (configurable)

Event	macOS	iPhone
Stop	Codex · project / Task completed	Reminder with the same text
PermissionRequest	Codex · project / Approval required	Reminder with the same text

The approval hook is notification-only. It never approves, denies, rewrites, or interrupts a request. Codex continues to show its normal Approve/Deny UI.

Requirements

• macOS with the Reminders app
• Codex CLI with lifecycle Hooks support
• The same Apple Account on the Mac and iPhone for iPhone delivery
• Reminders enabled in iCloud and notifications allowed on the iPhone

The implementation was tested with Codex CLI 0.149.1 on macOS 26.5.1. Codex Hooks can evolve, so the installation prompt checks the local Codex version and existing configuration before changing anything. See the official Codex Hooks documentation.

Install with Codex

The installation prompt is the installer. It is plain Markdown, so you can read every requested action before allowing Codex to run it.

1. Download FEED_THIS_TO_CODEX.md, or open it and copy the full contents.
2. Attach the file to Codex, or paste it into a new Codex session.
3. Ask Codex to follow the document and complete the installation.
4. Review the proposed file/configuration changes and approve only what you understand.
5. Restart Codex, run /hooks, and trust the new Stop and PermissionRequest hooks after reviewing them.

Chinese users can use 把我喂给codex.md, which installs the same script with Chinese selected.

The prompt writes an executable script and hook definitions under ~/.codex. Only use the prompt from a source you trust.

Commands

# Status
~/.codex/codex-native-notify.sh status

# Test notifications
~/.codex/codex-native-notify.sh test-complete
~/.codex/codex-native-notify.sh test-approval

# Global switch
~/.codex/codex-native-notify.sh on
~/.codex/codex-native-notify.sh off

# Device switches
~/.codex/codex-native-notify.sh mac-on
~/.codex/codex-native-notify.sh mac-off
~/.codex/codex-native-notify.sh iphone-on
~/.codex/codex-native-notify.sh iphone-off

# Event switches
~/.codex/codex-native-notify.sh complete-on
~/.codex/codex-native-notify.sh complete-off
~/.codex/codex-native-notify.sh approval-on
~/.codex/codex-native-notify.sh approval-off

# iPhone delay: 1–86400 seconds
~/.codex/codex-native-notify.sh delay 1

# Language
~/.codex/codex-native-notify.sh lang en
~/.codex/codex-native-notify.sh lang zh

All device and event switches are on by default. The default iPhone delay is 1 second. The English installation prompt selects English; the Chinese prompt selects Simplified Chinese.

Privacy and side effects

• All processing stays on your Mac. There is no project telemetry or external notification service.
• iPhone delivery uses iCloud Reminders, so the project directory name and notification text are stored in iCloud and may appear on your lock screen.
• Each iPhone notification creates a real reminder in the default Reminders list. Test and historical reminders remain until you delete them.
• The project name comes from the current Codex session directory's basename.

Troubleshooting

Hooks do not run

Start a new Codex session and run /hooks. Confirm both hooks are installed, active, and trusted. Non-managed hooks are skipped until you trust their exact definitions.

Mac notification does not appear

Run test-complete, then check macOS notification permissions for the terminal or application that launched Codex. A successful osascript call does not override Focus or notification settings.

iPhone notification does not appear

Confirm that Reminders sync is enabled for the same Apple Account on both devices, Reminders notifications are allowed on the iPhone, and the reminder was created on the Mac.

The delay is the reminder's future due time, not the duration of iCloud sync. The script sets the due date to now + delay. If that interval is too short, the reminder may already be due by the time it reaches the iPhone, so iOS may not show a banner. A longer interval gives iCloud more time to sync before the reminder becomes due:

~/.codex/codex-native-notify.sh delay 120

This only improves the chance of a banner and cannot guarantee delivery time; iCloud sync, Focus, and iOS notification policy remain outside this project.

Uninstall

Give FEED_THIS_TO_CODEX.md to Codex and ask it to run the uninstall section. It removes only this project's two hook handlers, script, and state directory while preserving unrelated Codex configuration.

Repository contents

• FEED_THIS_TO_CODEX.md: self-contained English installation prompt
• 把我喂给codex.md: self-contained Chinese installation prompt
• scripts/codex-native-notify.sh: auditable canonical script
• examples/hooks.json: hook shape example; do not overwrite an existing config
• docs/images: notification screenshots
• SECURITY.md: trust and privacy notes

License

MIT

Community

LINUX DO