# Notify Voice

> 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.

- Skill: `itswendell/notify-voice` (Agent Skill)
- Install (CLI): `npx skillmds@latest add itswendell/notify-voice`
- Raw SKILL.md: https://api.skillmd.com/api/skills/itswendell/notify-voice/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: itswendell (https://skillmd.com/u/itswendell)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/itswendell/notify-voice

---


# 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:

```bash
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:

```bash
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:

```bash
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 `--`.