debug-voice — Claude Code skill: log voice sessions
Installs dev-only logging for Grok realtime voice sessions and runs a fix loop from the log.
npx skills add cursor/plugins --skill debug-voice -a claude-codeWhat debug-voice 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.
What it helps with
- 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 for the agent
- /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
How to install debug-voice
1Skills CLI (Vercel)
npx skills add cursor/plugins --skill debug-voice -a claude-code2Manually: put the files in place
~/.claude/skills/debug-voice/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/debug-voice/
1Skills CLI (Vercel)
npx skills add cursor/plugins --skill debug-voice -a codex2Manually: put the files in place
.agents/skills/debug-voice/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add cursor/plugins --skill debug-voice -a cursor2Manually: put the files in place
.cursor/skills/debug-voice/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install cursor/plugins debug-voice2Manually: put the files in place
.github/skills/debug-voice/SKILL.md1Skills CLI (Vercel)
npx skills add cursor/plugins --skill debug-voice -a gemini-cli2Platform CLI
gemini skills install https://github.com/cursor/plugins --path grok-voice/skills/debug-voiceManually: put the files in place
.devin/skills/debug-voice/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add cursor/plugins --skill debug-voice -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about debug-voice
How do I install debug-voice in Claude?
Run npx skills add cursor/plugins --skill debug-voice -a claude-code. The skill lands in ~/.claude/skills/debug-voice/SKILL.md.
What does debug-voice do?
It wires a dev-only logging pipeline into your app: a client logger posts entries to a local NDJSON file, then the agent traces the failure from that log and fixes one thing at a time.
Do I need to configure anything for logs to be written?
Outside dev the sink returns 404 unless the VOICE_LOG=1 environment variable is set. The skill also adds .voice-logs to .gitignore.
