# debug-voice

Installs dev-only logging for Grok realtime voice sessions and runs a fix loop from the log.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 320 installs · ★ 14099
- Author: cursor
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cursor/plugins/tree/HEAD/grok-voice/skills/debug-voice/SKILL.md
- Updated: 2026-10-25
- HTML: https://affpapa.org/en/nevibecode/skills/debug-voice

## What it does

Reach for this when voice mode misbehaves and there is no way to see what happened in the session. The agent cannot hear your app, so the log becomes its ears and you stay the judge. It maps the project first, posts a plan of the edits, and stops there. Nothing gets changed until you reply with a go or strike the lines you do not want.

The install is a small contract written in your app's own language and conventions. A client logger buffers entries and posts them to `POST /api/voice/log` every second or at 200 entries; the sink appends NDJSON to `.voice-logs/<sessionId>.ndjson`. Hook points cover session start, token fetch, mic permission, socket state, client and server events, plus audio: incoming chunks aggregate into 2 s windows, and the first and last response deltas are counted by bytes and gaps. Audio itself never lands in the log, only byte counts and RMS. Tokens, keys and strings over 400 chars are stripped before buffering.

The sink answers `404` outside dev unless `VOICE_LOG=1` is set, which is what keeps the debug stream out of production. Then the fix loop starts: match your complaint to log signatures, change one thing, re-test.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill debug-voice -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/debug-voice/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/debug-voice/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill debug-voice -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/debug-voice/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill debug-voice -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/debug-voice/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install cursor/plugins debug-voice
```

2. **Manually: put the files in place**
- File: `.github/skills/debug-voice/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill debug-voice -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/cursor/plugins --path grok-voice/skills/debug-voice
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/debug-voice/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add cursor/plugins --skill debug-voice -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/cursor/plugins/tree/HEAD/grok-voice/skills/debug-voice/SKILL.md

## When to use it
- see what actually happened in a voice session after it ended
- add debug logging to a voice integration that has none
- tell a token or mic problem apart from an audio stream problem
- measure the delay between a server response and playback start
- check drops and underruns during barge-in

## Example prompts
- /debug-voice — voice mode sometimes goes silent, work it out from the log
- /debug-voice, audio cuts out on barge-in, I need a log
- /debug-voice — add voice logging, we have none at all

## Similar
- [debug-window](https://affpapa.org/en/nevibecode/hooks/debug-window.md) — hook · 189 installs
- [voice-dossier-builder](https://affpapa.org/en/nevibecode/skills/voice-dossier-builder.md) — skill · 1000 installs
- [voice-agents](https://affpapa.org/en/nevibecode/skills/sickn33-voice-agents.md) — skill · 890 installs
- [voice-analysis](https://affpapa.org/en/nevibecode/skills/voice-analysis.md) — skill · 445 installs
- [realtime](https://affpapa.org/en/nevibecode/skills/realtime.md) — skill · 634 installs
- [voice-call](https://affpapa.org/en/nevibecode/skills/voice-call.md) — skill · 3200 installs

From the same set: [cursor/plugins](https://affpapa.org/en/nevibecode/by/cursor/plugins.md) — 47 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md