The Voice System

export function isVoiceGrowthBookEnabled(): boolean {
  // feature('VOICE_MODE') is a compile-time constant (Bun bundler)
  // Dead code is eliminated in non-ANT builds — keeps binary size down.
  return feature('VOICE_MODE')
    ? !getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_quartz_disabled', false)
    : false
}

The GrowthBook flag tengu_amber_quartz_disabled defaults to false (not disabled). A missing or stale disk cache reads as "not killed" — so fresh installs work immediately. Flipping the flag to true emergency-disables voice for all users within GrowthBook's next cache refresh cycle.

export function hasVoiceAuth(): boolean {
  if (!isAnthropicAuthEnabled()) return false
  const tokens = getClaudeAIOAuthTokens()
  return Boolean(tokens?.accessToken)
}

getClaudeAIOAuthTokens() spawns security on macOS (~20-50ms cold, cached afterward). The memoize clears on token refresh (~once per hour), so one cold spawn per session is expected. API keys, Bedrock, Vertex, and Foundry all return false here — voice_stream is only available via Claude.ai OAuth.

Enabling voice runs five sequential checks before writing voiceEnabled: true to settings:

1. isVoiceModeEnabled() — auth + GB gate.
2. checkRecordingAvailability() — rejects remote environments (CLAUDE_CODE_REMOTE, Homespace) immediately; then probes the audio backend chain.
3. isVoiceStreamAvailable() — re-checks OAuth token freshness.
4. checkVoiceDependencies() — verifies at least one recording tool is usable.
5. requestMicrophonePermission() — fires the OS TCC dialog now (macOS) rather than on first keypress. Provides platform-specific guidance on denial.

// Fires TCC dialog early — better than a surprise on first hold-to-talk
if (!(await requestMicrophonePermission())) {
  const guidance = process.platform === 'darwin'
    ? 'System Settings → Privacy & Security → Microphone'
    : 'your system\'s audio settings'
  return { type: 'text', value: `Microphone access denied. Go to ${guidance}.` }
}

On WSL1 and headless Linux, arecord is installed but open() fails immediately because there is no ALSA card and no PulseAudio server. hasCommand('arecord') returns true in all these cases. The probe works by spawning arecord with the same arguments as the real recording session and racing a 150ms timer:

const timer = setTimeout((child, resolve) => {
  child.kill('SIGTERM')
  resolve({ ok: true, stderr: '' })   // still alive = opened OK
}, 150, child, resolve)

child.once('close', code => {
  clearTimeout(timer)
  resolve({ ok: code === 0, stderr: stderr.trim() }) // exited early = failed
})

The result is memoized — audio device availability does not change mid-session, and this runs on every voice keypress via checkRecordingAvailability().

const args = [
  '-q',               // quiet: no progress output
  '--buffer', '1024', // flush in small chunks; without this SoX buffers seconds
  '-t', 'raw',         // raw PCM, no WAV header
  '-r', '16000',      // 16kHz sample rate (matches STT endpoint requirement)
  '-e', 'signed',     // signed PCM
  '-b', '16',         // 16-bit depth
  '-c', '1',          // mono
  '-',                // write to stdout
]
// Silence detection (only when NOT in push-to-talk mode)
if (useSilenceDetection) {
  args.push('silence', '1', '0.1', '3%', '1', '2.0', '3%')
  // ↑ stop after 2 seconds of audio below 3% threshold
}

Push-to-talk passes { silenceDetection: false } — the user controls start and stop. The native NAPI module also ignores its built-in onEnd in push-to-talk mode.

The claude.ai Cloudflare zone uses TLS fingerprinting and blocks non-browser clients (JA3 fingerprint mismatch). The api.anthropic.com listener exposes the same private-api pod with the same OAuth auth but is on a CF zone that does not enforce browser-class TLS fingerprinting. Desktop dictation still uses claude.ai because Swift's URLSession has a browser-class JA3 fingerprint and passes the challenge.

// Override via env var for testing/staging
const wsBaseUrl =
  process.env.VOICE_STREAM_BASE_URL ||
  getOauthConfig().BASE_API_URL
    .replace('https://', 'wss://')
    .replace('http://', 'ws://')

finalize() returns a Promise<FinalizeSource> that resolves via whichever of four paths fires first:

The no_data_timeout path is the silent-drop signature — if it fires with hadAudioSignal=true, the session hit a known server bug (sticky CE pod returning zero transcripts, ~1% of sessions).

While the user holds Space for warmup, some space characters leak into the text input before stopImmediatePropagation() takes effect (listener registration order is not guaranteed). stripTrailing() removes exactly the leakage count without touching pre-existing spaces at the boundary:

// Strip exactly `maxStrip` trailing `char` chars, leaving `floor` behind
const stripTrailing = (maxStrip, { char = ' ', anchor = false, floor = 0 } = {}) => {
  // Also counts full-width spaces (U+3000) for CJK IME compatibility
  const scan = char === ' '
    ? normalizeFullWidthSpace(beforeCursor)
    : beforeCursor
  // ...
  if (anchor) {
    voicePrefixRef.current = stripped         // save text before cursor
    voiceSuffixRef.current = afterCursor      // save text after cursor
  }
}

When anchor=true, the call also captures the cursor position for interim transcript injection. The gap space inserted between prefix and suffix ensures the waveform cursor sits on the gap rather than the first suffix letter.

// In useVoice.ts
const RELEASE_TIMEOUT_MS = 200    // gap that signals key release (auto-repeat is 30-80ms)
const REPEAT_FALLBACK_MS = 600    // arm release timer if no auto-repeat seen yet
const FIRST_PRESS_FALLBACK_MS = 2000 // modifier combos: OS initial repeat delay up to ~2s

When no second keypress arrives within 600 ms, the fallback timer arms the release detection. For modifier combos, callers pass 2000 ms to cover the long OS initial repeat delay (macOS slider at "Long" = ~2 s before auto-repeat starts).

All six conditions must be true to trigger a replay:

1. finalizeSource === 'no_data_timeout'
2. hadAudioSignal === true (non-trivial mic signal detected)
3. wsConnected === true (WS did open — backend received audio)
4. !focusTriggered (not a focus-mode session)
5. accumulatedRef.current.trim() === '' (no partial transcript accumulated)
6. !silentDropRetriedRef.current (replay only once per session)

if (finalizeSource === 'no_data_timeout' && hadAudioSignal && wsConnected
    && !focusTriggered && focusFlushedChars === 0
    && accumulatedRef.current.trim() === ''
    && !silentDropRetriedRef.current
    && fullAudioRef.current.length > 0) {
  silentDropRetriedRef.current = true
  await sleep(250)          // backoff to clear rapid-reconnect same-pod race
  if (isStale()) return

  // Replay full buffer in 32 KB slices on a fresh connection
  const SLICE = 32_000
  for (const chunk of replayBuffer) {
    // ... batch into SLICE-sized sends ...
    conn.send(Buffer.concat(slice))
  }
  await conn.finalize()
}

The audio buffer is bounded: fullAudioRef.current skips buffering in focus mode (where sessions can last minutes and the buffer could reach ~20 MB). The 32 KB slice size batches small NAPI chunks into a reasonable WS frame size without exceeding WS message limits.

// Arms / resets the silence timer after each flushed transcript
function armFocusSilenceTimer(): void {
  if (focusSilenceTimerRef.current) clearTimeout(focusSilenceTimerRef.current)
  focusSilenceTimerRef.current = setTimeout(() => {
    if (stateRef.current === 'recording' && focusTriggeredRef.current) {
      silenceTimedOutRef.current = true
      finishRecording()           // tears down WS gracefully
    }
  }, FOCUS_SILENCE_TIMEOUT_MS)   // 5000 ms
}

Keyterms come from three sources, merged into a deduplicated Set:

1. Global hardcoded terms: MCP, symlink, grep, regex, localhost, TypeScript, OAuth, webhook, gRPC, dotfiles, subagent, worktree. (Claude and Anthropic are already base keyterms on the server.)
2. Project root basename: e.g., claude-code added as a whole term.
3. Git branch words: feat/voice-keyterms → ["feat", "voice", "keyterms"].

export function splitIdentifier(name: string): string[] {
  return name
    .replace(/([a-z])([A-Z])/g, '$1 $2')  // camelCase → camel Case
    .split(/[-_./\s]+/)                    // split on separators
    .filter(w => w.length > 2 && w.length <= 20) // discard noise
}

export function useVoiceEnabled(): boolean {
  const userIntent   = useAppState(s => s.settings.voiceEnabled === true)
  const authVersion  = useAppState(s => s.authVersion)
  // authVersion bumps on /login only.
  // getClaudeAIOAuthTokens() spawns `security` (~60ms cold) — can't call on every render.
  const authed = useMemo(hasVoiceAuth, [authVersion])
  return userIntent && authed && isVoiceGrowthBookEnabled()
}

The isVoiceGrowthBookEnabled() call stays outside the memo so a mid-session kill-switch flip takes effect on the next render without waiting for a login event.