Voice and dictation

Dictation converts speech into editable prompt text while keeping the terminal session open. It is a composer input method: review the transcript before submitting it as an instruction to the agent.

Start a conversational voice call

For a live conversation rather than composer transcription, run:

/voice

Use headphones and grant microphone permission to the terminal application. A local call requires a ChatGPT subscription sign-in; an API key alone is not a substitute. In an organization-bound session, the call uses that organization's gateway instead of silently switching to a local account. Listen for connection confirmation before speaking sensitive material.

The call can delegate work to the coding agent in the current session. Delegated work remains serialized with typed turns and keeps the existing tools and approvals. Complete required approvals in the application; spoken intent does not bypass them. Use Ctrl+C or the application's Stop control to hang up. Ending a call does not roll back work already performed.

If connection fails, inspect /accounts and /usage, model access, microphone permission and audio devices. A rate-limited voice account needs an available ChatGPT account. Voice signaling keeps one admitted credential; it does not retry an ambiguously created call with another identity. This workflow is separate from the transcription routing table below.

Embedding a native call instead? See the native voice, mobile and media contracts for capture/playback ownership, pairing and transport lifetimes. An exported media interface does not imply that a phone or desktop application ships here.

Dictate a prompt

1. Open an interactive agent session and select a supported model.
2. Place the cursor where you want the transcript inserted.
3. Press Ctrl + R and speak a short instruction.
4. Press Enter to stop recording, or Esc to cancel.
5. On macOS the transcript is inserted at the cursor. Correct paths, identifiers, and punctuation, then submit the completed prompt normally.

For a first check, dictate “Explain this repository without changing files.” Confirm that the words appear in the composer and that the session remains open. Do not test by speaking credentials or sensitive customer information.

Provider routing

Choosing Claude does not mean audio is sent to Anthropic. Check the routing above before recording material subject to a provider-specific data policy. Model access and transcription access are separate capabilities.

Credentials and language

OpenAI dictation can use a managed account or credentials from CODEX_ACCESS_TOKEN, CODEX_AUTH_JSON, $CODEX_HOME/auth.json (default ~/.codex/auth.json), OPENAI_API_KEY, or CODEX_API_KEY. Configure credentials through authentication; do not paste them into a prompt.

xAI defaults to English. Set XAI_STT_LANGUAGE in the environment before launching the agent to request another language, for example Portuguese:

XAI_STT_LANGUAGE=pt agent-cli --provider xai

Streaming and fallback

OpenAI subscription authentication uses the subscription-backed streaming protocol. If streaming fails, the same captured recording can be submitted to the buffered ChatGPT transcription route. API keys use the public OpenAI Realtime API. Both OpenAI routes can update the composer during recording.

The organization gateway streams partial transcripts where supported. Older gateways and interrupted streams can use a final-only upload on the same endpoint with the same captured recording. That fallback does not switch to a local account or a different provider destination.

Diagnose dictation

For other composer controls, see keybindings.