| name | pk-speak |
| description | Use when a CLI agent should speak naturally with pk-speak, wrap a command with spoken lifecycle notices, start the phone gateway/tray, print Android setup QR codes, or explain the current realtime voice options. Keep normal replies concise and speak only useful status, questions, approvals, and completion summaries. |
pk-speak
Use pk-speak as the local voice layer for CLI agents.
Fast Path
- Check setup:
pk-speak doctor
- Speak a short status:
pk-speak speak "Build finished"
- Speak piped text:
git status --short | pk-speak speak --provider edge
- Generate audio without playback:
pk-speak speak --no-play --output reply.mp3 "Tests passed"
- Wrap an agent or command:
pk-speak wrap -- codex
- Wrap with a friendly label:
pk-speak wrap --label "Claude Code" -- claude
- Start desktop tray and gateway:
pk-speak tray
- Start headless gateway only:
pk-speak gateway
- Print Android setup/download QR:
pk-speak mobile
- Open session admin pane:
pk-speak admin
Prefer pk-speak speak for one-off voice notices and pk-speak wrap when launching another CLI.
Speak Naturally
Speak only what helps the user stay oriented:
- start/finish/failure notices
- approval requests
- short blockers
- concise summaries of completed work
- one clarifying question when needed
Do not read long logs, diffs, stack traces, or full command output aloud. Summarize them first, then speak the summary.
Good spoken style:
Tests failed in the session routing suite. I found one assertion drift and I am fixing it now.
Bad spoken style:
Reading the entire error output line by line...
Providers
pk-speak speak supports the saved setup profile and provider overrides such as:
autoedgeelevenlabsopenaisaglegacy
Use --dry-run before speaking if you need to inspect the selected provider and text.
Realtime Voice
This repo has Gemini Live realtime pieces, but use the turn-based path unless the user explicitly asks for realtime testing:
- Smoke test:
pi-speak-gemini-live-smoke
- Gateway realtime path:
pk-speak gateway with AGENT_PROVIDER=gemini-live
- WebSocket route:
/v1/live in the local gateway
Realtime provider keys must stay server-side. Do not put Gemini, Vertex, OpenAI, or ElevenLabs keys in the Android/browser client.
When More Context Is Needed
Read only the relevant reference:
- Old-agent bootstrap prompt:
references/bootstrap-prompt.md
- Realtime notes and commands:
references/realtime.md
- Full command docs:
README.md
- Root extension pointer:
SKILL.md
- Gateway source:
pk-speak.ts, headless-gateway.ts, realtime-gateway.ts, gemini-live-turn.ts
