| name | speak-swiftly-codex-hooks |
| description | Use when a user wants Speak Swiftly to read Codex replies aloud automatically through Codex lifecycle hooks, including plugin-managed hook setup, hook command path diagnosis, hook doctor interpretation, duplicate-hook diagnosis, centralized hook logs, final-reply TTS troubleshooting, or validation from another working directory. |
Speak Swiftly Codex Hooks
Use this skill when the task is about Codex lifecycle hooks that send final assistant replies to the local Speak Swiftly service.
Start Here
- Read docs/codex-hooks-tts.md before changing guidance or setup. It is the repo source of truth for the plugin hook, command path behavior, logs, state, and known Codex payload behavior.
- Verify the live service before changing hook config: read
speak-swiftly://overview or run node scripts/codex-hooks-doctor.mjs --repair-plan from the repository root.
- Treat
speak-swiftly@socket as the preferred plugin entry when both Socket and standalone marketplaces are present.
- Keep the legacy
speak-swiftly-server@socket config entry disabled unless the user explicitly asks for legacy-plugin investigation.
- For plugin-managed hooks, confirm both
features.hooks = true and features.plugin_hooks = true in ~/.codex/config.toml; current Codex CLI source gates runnable plugin hooks behind the separate plugin_hooks feature.
- Codex 0.129.0 stores per-hook review decisions under
[hooks.state] in ~/.codex/config.toml; if Codex says hooks need review, use the hooks settings panel to approve the Speak Swiftly Stop command instead of adding a user-level fallback hook.
Setup Model
- Preferred install surface: the Speak Swiftly plugin manifest declares
hooks: "./hooks/hooks.json", and installed plugins can bundle lifecycle config through that manifest.
- Do not copy the repo-local
.codex/hooks.json into ~/.codex/; that command sets CODEX_HOOK_TTS_DATA_DIR for checkout-scoped development logs and state. Do not add a user-level ~/.codex/hooks.json Speak Swiftly hook for normal installs.
- Plugin-managed hook commands must target the installed Socket Codex cache payload path at
~/.codex/plugins/cache/socket/speak-swiftly/12.0.0/hooks/.... Do not keep stale standalone SpeakSwiftlyServer cache commands in the Socket-managed manifest.
- Keep the shipped plugin hook set limited to the
Stop hook. Do not add a PermissionRequest probe unless the release explicitly reintroduces approval-prompt diagnostics.
Doctor Interpretation
- Warn on user-level hooks that point at
.codex/hooks/stop-tts.mjs, include CODEX_HOOK_TTS_DATA_DIR, or duplicate the plugin-managed Stop hook. Treat them as duplicate or legacy repair targets, not fallback hooks.
- Warn on duplicate enabled plugin entries. Keep the canonical Socket entry and disable or remove duplicate standalone or legacy plugin entries after confirmation.
- Warn when the expected
speak-swiftly@socket:hooks/hooks.json:stop:0:0 entry is missing from [hooks.state]; that means the new Codex per-hook review gate probably still needs operator approval.
- Runtime default voice mismatch is not automatically a hook failure. The hook uses the runtime default voice unless
CODEX_HOOK_TTS_PROFILE_NAME is set; when an override is configured, confirm that profile exists in the cached voice inventory.
Validation
- Validate syntax and focused fixtures with
sh scripts/repo-maintenance/validations/25-codex-plugin.sh.
- Run
node scripts/codex-hooks-doctor.mjs --repair-plan and inspect both centralized and repo-local recent stop-hook log summaries.
- To prove all-directory coverage, run a tiny Codex CLI turn from a different working directory and then tail
~/.codex/speak-swiftly-server/hooks/logs/stop-tts.jsonl.
- Treat a queued log entry with the probe
cwd, sessionId, turnId, and request.request_id as the proof that the hook fired and the service accepted the speech request.
- If the installed plugin manifest is correct but no
Stop row appears, check features.plugin_hooks before adding any user-level fallback.
Troubleshooting
- If a direct manual run of the installed plugin's
hooks/stop-tts.mjs queues speech but normal assistant final replies do not add a fresh row to ~/.codex/speak-swiftly-server/hooks/logs/stop-tts.jsonl, inspect whether the plugin-managed commands still include stale direct commands for absent cache paths before blaming the live service.
speech-route-unreachable means the hook could not reach the local HTTP route.- HTTP
503 from /speech/live means the service is reachable but not ready for speech work yet.
duplicate-turn means shared dedupe blocked a repeated session_id + turn_id; that is expected when more than one matching hook source starts.structured-assistant-metadata means Codex produced compact UI or automation metadata instead of speakable final prose.- If the live service itself is unhealthy, switch to
$speak-swiftly-launchagent-setup for service setup or $speak-swiftly-runtime-operator for runtime readiness, queue, playback, or backend state.
