Codex CLI Hooks
https://github.com/shanraisshan/codex-cli-hooks- Category
- Developer Tools
- Rank
- No. 1983Tools index
- Pricing
- Open Source
- Type
- TOOL
- Builder
- shanraisshan
- GitHub
- 71 stars
- Date
About
Adds voice feedback on each Codex CLI hook for an agentic coding workflow.
What it does
A small Python event handler turns Codex activity into audible cues. It reacts before and after tool use, around context compaction, when approval is requested, when prompts arrive, and at session boundaries. Each event selects a matching sound, while session startup also prints a short context string.
Why it's ranked here
The focused design is easy to understand and adapt, with broad event coverage and explicit operating-system handling. Tests cover argument parsing, event mappings, configuration behavior, audio selection, traversal protection, logging, and several integrated event paths. Documentation and implementation disagree about the richness of startup context, which weakens confidence.
What's good
One handler serves every supported event, keeping behavior consistent. Individual cues and logging can be disabled through layered configuration. Sound names reject traversal patterns before path construction. Audio playback runs asynchronously on macOS and Linux, so a cue should not hold up the coding session.
Tradeoffs
Linux depends on finding one of several external audio players, while macOS and Windows use built-in facilities. Failures often return quietly, and the program exits successfully even after unexpected errors. Startup context is only a fixed phrase in the supplied implementation, despite documentation promising date, branch, working tree, and directory details.
How to use it well
Use it when audible state changes help you follow long or partially unattended Codex sessions. Enable the events that carry useful meaning and mute noisy tool-level cues. It fits project-local hook customization for macOS, Linux, and Windows. It does not provide workflow automation, richer notifications, or the detailed startup context described by its documentation.
Technical notes+
.codex/hooks.json registers eight command hooks, each invoking .codex/hooks/scripts/hooks.py with an event argument and a ten-second timeout. The handler reads optional JSON from stdin, records selected fields in a JSON Lines log unless disabled, checks per-event toggles, prints hooks context: run for SessionStart, and maps recognized events to same-named WAV or MP3 assets. macOS uses afplay; Linux probes paplay, aplay, ffplay, then mpg123; Windows uses winsound and WAV only. tests/test_hooks.py exercises parsing, mappings, configuration precedence, logging controls, platform selection, traversal rejection, and integration paths. .codex/hooks/HOOKS-README.md claims startup output includes date, branch, working-tree state, and directory, but the supplied handler does not gather those values. Platform-specific registration templates appear in install/hooks-mac.json, install/hooks-linux.json, and install/hooks-windows.json.
Observed
- Primary language
- Python 3
- Interface
- Codex CLI command hooks receiving event names as arguments and optional JSON through standard input
- Supported platforms
- macOS, Linux, and Windows
- Installation surface
- Project-local hook folder plus platform-specific JSON registration templates
- Packaging
- Plain Python and JSON assets with no build step or package manager
- Hook coverage
- Eight events: session start, prompt submission, pre-tool use, permission request, post-tool use, stop, pre-compaction, and post-compaction
- Tests
- A unittest suite covers parsing, mappings, configuration, audio selection, logging, security checks, and integration behavior
Read from README.md, .codex/hooks/scripts/hooks.py, tests/test_hooks.py, AGENTS.md, CLAUDE.md, .codex/hooks.json, .github/FUNDING.yml, .vscode/settings.json, install/README-mac.md, install/hooks-mac.json, install/README-linux.md, install/hooks-linux.json, install/README-windows.md, install/hooks-windows.json, .codex/hooks/HOOKS-README.md.
What it can do
Provide voice feedback on code generation hooks
Codex CLI code generation events → Spoken audio feedback
Monitor Codex CLI workflow execution
Active Codex CLI session → Real-time hook event detection
Convert CLI hook events to voice notifications
Hook trigger events and status updates → Audio announcements of coding workflow progress
Enable hands-free coding workflow awareness
Codex CLI operations and results → Voice-based status updates without visual monitoring
Integrate with agentic coding processes
Automated coding agent workflows → Voice feedback on autonomous code generation steps
Tags
Tech Stack
Media
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.