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.