Breakdown
A voice-driven AI code explainer. Select a line in VS Code, run a command,
and the AI explains it aloud. Navigate line by line with keyboard shortcuts.
Interrupt at any time with a typed question.
Setup
1. Requirements
- Docker installed and running (used
to host a local LiveKit server — no account or cloud project needed)
- Python 3.11+ available on your PATH (used to install Breakdown's core via
uv or pip)
- An API key from at least one supported LLM/TTS provider (OpenAI covers
LLM, TTS, and embeddings with a single key)
2. Start a session
Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run
Breakdown: Start Session, or press Cmd+K Cmd+E (macOS) /
Ctrl+K Ctrl+E (Windows/Linux).
The first time you do this, Breakdown will:
- Prompt to install its Python core if it isn't found (
breakdown-ai, via
uv tool install or pip install --user)
- Start a local LiveKit server automatically via Docker Compose
- Prompt you for an API key, stored using VS Code's encrypted secret
storage — no
.env file needed
Every subsequent Start Session skips straight to connecting, since the
Python core, LiveKit, and your API key all persist.
If you'd rather point at a LiveKit Cloud project instead of running Docker
locally, run Breakdown: Set API Key and set LIVEKIT_URL,
LIVEKIT_API_KEY, and LIVEKIT_API_SECRET — Breakdown skips the Docker
step whenever LIVEKIT_URL is already configured.
3. Explain some code
Open a file, place your cursor on a line, and run Breakdown: Explain Line
(Cmd+Alt+I / Ctrl+Alt+I). The explanation appears in the Breakdown
sidebar and is narrated aloud.
The first time narration plays, click anywhere in the Breakdown sidebar (or
press a key) if you see an "enable narration audio" banner — browsers
require one user gesture before allowing audio playback.
Keyboard Shortcuts
| Action |
macOS |
Windows / Linux |
| Start session |
Cmd+K Cmd+E |
Ctrl+K Ctrl+E |
| Explain line |
Cmd+Alt+I |
Ctrl+Alt+I |
| Next line |
Cmd+K Cmd+N |
Ctrl+K Ctrl+N |
| Previous line |
Cmd+K Cmd+P |
Ctrl+K Ctrl+P |
| Ask a question |
Cmd+K Cmd+Space |
Ctrl+K Ctrl+Space |
| Stop session |
Cmd+K Cmd+Q |
Ctrl+K Ctrl+Q |
All shortcuts are configurable in VS Code's keyboard settings. Manage API
keys any time via Breakdown: Set API Key in the Command Palette.
Troubleshooting
- "Docker isn't running": install/start Docker Desktop, or set
LIVEKIT_URL via Breakdown: Set API Key to use LiveKit Cloud instead.
- No narration audio: click inside the Breakdown sidebar once per VS
Code window — this is a one-time browser autoplay restriction.
- Stuck on "connecting": run
Breakdown: Stop Session then
Breakdown: Start Session again.
Links
License
MIT
