Voice Dictation (/voice)

Speak your prompt instead of typing it.

Overview

The /voice command (alias /record) records audio from your microphone and streams real-time transcripts directly into the prompt box as you speak. You can also start dictation at any time using the F5 key.

Voice dictation writes text into the prompt box; it does not automatically submit your prompt. When you stop recording, the transcript remains in the prompt box exactly as if you had typed it, allowing you to edit, expand, and submit the text when you are ready.

Caution

Sign out and sign back in first. Voice dictation requires an updated authentication permission granted at sign-in. If your active session was authenticated before voice dictation became available, transcription will fail. Run /logout, sign in again, and retry. This is a one-time setup step.

Dictating a prompt

To dictate a prompt into the terminal, follow these steps:

1. Press F5, or type /voice in the prompt box and press Enter.
2. Wait for the status line below the prompt to transition from Connecting… to Recording.
3. Speak clearly into your microphone. Interim text appears in the prompt box and updates as the transcription service processes audio.
4. Press Enter (or F5) to stop recording and retain the transcript in the prompt box.

While a recording session is active, the status line below the prompt displays the elapsed recording time and available shortcut actions:

● Recording 0:07  enter or f5 to insert · esc to discard

Dictation controls

The following keyboard shortcuts control active dictation sessions. All other keystrokes are ignored during recording to prevent accidental input:

Key	Action
Enter (or F5)	Stop recording and insert the transcript into the prompt.
Esc	Discard the recording and restore previous prompt contents.
Ctrl+Z (after)	Revert the entire dictation as a single undo operation.

If the prompt box already contained text before starting dictation, the transcript is appended to the existing text rather than replacing it.

Note

The F5 key is remappable. Use /keybindings to bind voice.start_dictation to a different shortcut; the on-screen hint will automatically update to reflect your custom keybinding.

Availability

Voice dictation is subject to the following operating constraints:

• Dictation requires an interactive TUI session and is disabled in non-interactive print mode (--print).
• Dictation is not currently supported for business or enterprise accounts.

Voice over SSH

When the CLI runs on a remote machine over Secure Shell (SSH), the remote environment lacks direct access to your local audio hardware. The mic-serve subcommand resolves this by streaming audio from your local microphone over a local loopback socket, which is forwarded to the remote CLI through a reverse SSH tunnel.

The Antigravity CLI must be installed on both your local machine and the remote host.

1. Serve your local microphone

Start the microphone server on your local machine:

agy mic-serve

Keep this process running while dictating. By default, mic-serve listens on 127.0.0.1:4713 and streams audio from your default input device to connected clients. You can run it inside a background job, a tmux pane, or a separate terminal window.

To bind to a custom port if port 4713 is already occupied, specify the --addr flag:

agy mic-serve --addr 127.0.0.1:<UNUSED_PORT>

Caution

Keep mic-serve on localhost (127.0.0.1). The microphone server is intended for local connections forwarded through SSH tunnels. Keep it bound to loopback so external devices on your network cannot access the audio stream.

2. Open a reverse tunnel

From your local machine, forward the local audio port to the remote machine by opening a reverse SSH tunnel:

ssh -R 24713:localhost:4713 <remote-machine>

The tunnel must remain active during dictation. To run the tunnel in the background without maintaining an interactive shell session, use the -f and -N flags with the ssh command. For example:

ssh -f -N -R 24713:localhost:4713 <remote-machine>

3. Start the CLI with ANTIGRAVITY_MIC

In your remote SSH session, launch the CLI with the ANTIGRAVITY_MIC environment variable set to the forwarded tunnel port. For example:

ANTIGRAVITY_MIC=localhost:24713 agy

If you are using a Windows remote host and use PowerShell, set the environment variable and start the CLI:

$env:ANTIGRAVITY_MIC = "localhost:24713"; agy

Alternatively, if you are using a Windows remote host, but use Windows Command Prompt (cmd.exe):

set ANTIGRAVITY_MIC=localhost:24713 && agy

In the CLI, press F5 or use /voice, and speak into your microphone. The local mic-serve process logs a confirmation when the CLI initiates an audio connection. For example:

Recording for 127.0.0.1:54134.

4. Verify the tunnel connection

If no connection log appears in the mic-serve output when dictating, test whether the forwarded port is reachable by capturing a raw audio sample on the remote host. For example:

timeout 5 nc localhost 24713 > /tmp/mic.raw

If /tmp/mic.raw accumulates data at approximately 32 kB/s, audio streaming across the reverse tunnel is operating correctly.

Troubleshooting

• Transcription fails with a permissions message: Your stored credentials predate voice dictation support. Execute /logout, sign in again to refresh permissions, and retry. Note that voice dictation is not available for business or enterprise accounts.
• Nothing is transcribed and the recording is silent: The active terminal process lacks operating system microphone permissions (the terminal running the CLI for local sessions, or the terminal running agy mic-serve for SSH sessions):
  • macOS: Approve the system permission dialog, or grant access under System Settings → Privacy & Security → Microphone. Restart your terminal using CmdQ to apply the updated permission.
  • Windows: Enable microphone access under Settings → Privacy & Security → Microphone, and ensure Let desktop apps access your microphone is enabled.
• Connecting fails immediately over SSH: No process is listening on the forwarded port. Verify that both agy mic-serve on your local machine and the ssh -R reverse tunnel are running.
• Dictation reports that the microphone server closed the connection: The server process terminated or the network tunnel dropped. Inspect the output of agy mic-serve on your local machine for detailed error diagnostics.
• The wrong microphone is used: mic-serve captures audio from the system default input device. Verify your default input hardware under System Settings → Sound → Input (macOS) or Settings → System → Sound → Input (Windows).
• The transcript is choppy or drops words: Audio is streamed uncompressed across the SSH tunnel; high latency or bandwidth saturation on the SSH connection can result in dropped audio packets.

Next steps

• CLI Reference: See all available slash commands and keybindings.
• Prompting & Interaction: Multiline editing, interrupts, and pasting media into the prompt.
• Installation & Auth: Sign-in flows, including the remote SSH OAuth loop.