notify-voice

name

notify-voice

description

Send concise, source-attributed updates from a local Codex task to the user's native ChatGPT Voice task with chatgpt-voice. Use during nontrivial or long-running work when a major milestone completes, a verified insight materially changes the conclusion, a blocker or important failure occurs, the task completes, or immediately before requesting user input or permission. Do not use for routine progress or unchanged monitoring.

Notify Voice

Use chatgpt-voice as a best-effort side channel. Continue to provide normal commentary and final responses in the originating task.

Decide whether to notify

Notify for:

• input-required: Notify immediately before asking a blocking question.
• permission-required: Notify immediately before triggering or requesting approval.
• blocker: Notify when progress cannot continue without an external change.
• failed: Notify when an important operation fails and needs attention.
• milestone: Notify at a meaningful phase boundary in long-running or background work.
• insight: Notify only for a verified finding that materially changes the conclusion, recommended action, risk, or expected outcome.
• completed: Notify after meaningful background or long-running work completes.

Do not notify for routine tool calls, minor progress, self-recovered errors, unchanged monitoring results, or facts already sent in another notification.

Check the fast environment gate

Before invoking chatgpt-voice notify, inspect CHATGPT_VOICE_NOTIFICATIONS. If it is explicitly disabled, do not invoke the notification command:

case "${CHATGPT_VOICE_NOTIFICATIONS:-}" in
  0|[fF][aA][lL][sS][eE]|[nN][oO]|[oO][fF][fF]|[dD][iI][sS][aA][bB][lL][eE][dD])
    exit 0
    ;;
esac
chatgpt-voice notify --kind milestone "The build passed."

An unset variable is not a denial. Continue to the CLI, which enforces its persistent notification setting. Values such as on, true, and 1 explicitly enable notifications and override persistent config.

Send the notification

Use one concise sentence and include the requested action when applicable:

chatgpt-voice notify --kind input-required \
  "I need you to choose staging or production before I can continue."

Choose priority as follows:

• Use urgent for input, permission, blockers, and important failures. These kinds already default to urgent and activate Voice.
• Use normal for milestones and completion when timely interruption is useful.
• Use quiet for nonurgent insights or updates. Quiet notifications are delivered without activating Voice.

Examples:

chatgpt-voice notify --kind milestone \
  "The failure is reproduced and isolated to token refresh; I am testing the fix."

chatgpt-voice notify --kind insight --priority quiet \
  "The latency regression comes from one missing index, not the model upgrade."

chatgpt-voice notify --kind permission-required \
  "The release is ready; approve the deployment in this task if you want me to proceed."

chatgpt-voice notify --kind completed \
  "The production health sweep completed with no critical findings."

The CLI automatically validates and attaches CODEX_THREAD_ID as the source task ID when available. Do not copy, infer, or invent a task ID. Use --source-thread <id> only when deliberately relaying for another known task.

Preserve safety and signal

• Send at most one notification per event or state change.
• Keep details in the originating task; send only the summary and next action.
• Notify before a predictable approval prompt because execution may pause at the prompt.
• Do not treat a cross-task or Voice relay as authorization for destructive, external, or permission-gated actions. Require approval in the source task.
• Do not notify from the Voice task itself. The CLI also suppresses a notification when its source and target task IDs match.
• Treat delivery as best effort. If chatgpt-voice is unavailable or fails, continue the main task and do not retry more than once.
• Rely on Voxport's default stale-notification expiry. Use --no-expiry only when the user explicitly wants an update retained indefinitely.
• Let the Voice agent close a transient session after ten seconds without a response. Use --keep-open only when the user explicitly wants the session to remain active without that delegated instruction.
• Respect the user's configured wake microphone mode. Do not add --wake-microphone unless the user explicitly requests a one-delivery override.
• Avoid shell-sensitive substitutions in notification text. Pass literal, concise text and use -- before text that starts with --.