royal-lobster/code-explainer

Code Explainer

✨ Interactive code walkthroughs with editor highlighting and AI-powered voice narration.

A coding agent skill that scans your codebase, builds a walkthrough plan, and explains code segment-by-segment — highlighting lines in VS Code / Cursor with a dedicated sidebar panel and narrating with natural-sounding local TTS. Works with Claude Code, Codex, OpenCode, Kilo Code, Amp, and more.

🎬 Watch Demo  ·  📝 Read Writeup

---

🚀 Features

• 🪟 VS Code Sidebar — Dedicated sidebar panel with walkthrough controls, segment navigation, and live explanation display
• 🎯 Code Highlighting — Automatically opens files, scrolls to code, and highlights 1–8 line ranges with per-highlight explanations
• 🔊 Local TTS — Natural-sounding voice narration powered by Kokoro-82M (#1 ranked open-source TTS), running locally on Apple Silicon via mlx-audio
• 🎬 Three Modes — Walkthrough (hands-free with TTS), Read (text in terminal), or Podcast (single audio file)
• 🧠 Adaptive Depth — Overview or Deep Dive explanations based on your familiarity
• 📋 Plan-First — Scout finds files, planner builds narrative order, parallel segment agents generate highlights — outline visible immediately, segments stream in as they finish
• 💾 Save & Share — Save walkthroughs to .walkthrough.json files, replay later or share with teammates via the repo
• ⌨️ Keyboard Shortcuts — Full keybinding support for hands-free navigation

📦 Requirements

• 🍎 macOS (Apple Silicon recommended for GPU-accelerated TTS)
• 🐍 Python 3.10+
• 📗 Node.js 18+
• 🖥️ VS Code or Cursor with CLI enabled (code or cursor command)

🔧 Installation

Just tell your coding agent:

Install the code explainer skill from https://github.com/Royal-lobster/code-explainer

Your agent will clone the repo into the skills directory, run setup.sh, and ask you to reload your editor — all while keeping you in the loop at each step.

💬 Usage

In your coding agent:

/explainer the authentication system

Or naturally:

Explain how the matching engine works
Walk me through the order flow
How does the WebSocket gateway handle events?

⚙️ How It Works

1. 💬 You ask to explain a feature
2. 🎯 Asks your depth preference (Overview / Deep Dive) and delivery mode
3. 🔍 Scout sub-agent maps the codebase — discovers relevant files and call chain

Overview path (fast):
4. 📋 Single agent builds plan + highlights in one pass → sends set_plan

Deep Dive path (thorough):
4. 🗺️ Planner builds narrative order + transition objects
5. ⚡ Parallel segment agents generate dense highlights
   Waits for all agents to finish, then sends full set_plan to sidebar

6. ✅ Plan in sidebar + chat — approve, reorder, or skip before playback starts
7. 🔄 Walkthrough runs based on your chosen mode:
   Walkthrough — sidebar drives playback automatically with TTS narration
   Read        — step through explanations in terminal, highlights code as you go
   Podcast     — renders a single audio file of the entire walkthrough
8. 📝 Summarizes key takeaways

🎬 Modes

🪟 Sidebar Controls

The VS Code sidebar provides buttons for all walkthrough controls:

• ▶️ Play / Pause — Toggle walkthrough playback
• ⏭️ Next / Previous — Navigate between highlights within a segment
• ⏩ Next / Previous Segment — Jump between segments
• ⏩ Speed — Adjust TTS playback speed
• 🔈 Volume — Adjust TTS volume
• 🗣️ Voice — Select TTS voice
• 🔇 Mute / Unmute — Toggle voice narration
• 🔄 Restart — Restart walkthrough from the beginning
• 💾 Save — Save current walkthrough to .walkthroughs/ for later replay
• ✕ Close — Close walkthrough (prompts to save if unsaved)

💾 Save & Share

Save walkthroughs as portable JSON files that live in your repo:

# Save via CLI
./scripts/explainer.sh save auth-flow

# Load a saved walkthrough
./scripts/explainer.sh load auth-flow

# List all saved walkthroughs
./scripts/explainer.sh list

Or use the VS Code command palette:

• Code Explainer: Save Walkthrough — Save with a custom name
• Code Explainer: Load Walkthrough — Browse and load saved walkthroughs

Saved walkthroughs are stored in .walkthroughs/ at the workspace root with relative file paths, so teammates can pull them and replay on their own machine. The sidebar also shows a browse list of saved walkthroughs when no walkthrough is active.

⌨️ Keyboard Shortcuts

All shortcuts are active when a walkthrough is running:

💬 Text Controls

You can also type commands in your agent’s chat:

🗣️ Voice Configuration

Code Explainer uses Kokoro-82M via mlx-audio for high-quality local TTS. Falls back to macOS say if unavailable.

# Change voice
export TTS_VOICE=am_adam    # American male

# Change speed
export TTS_SPEED=1.2        # 20% faster

🎤 Available Voices

🏗️ Architecture

The extension runs an HTTP + WebSocket server on localhost for communication between your coding agent and the VS Code sidebar.

Coding Agent ──HTTP──▶ Extension Server ──Events──▶ Sidebar Webview
                           │                            │
                      Highlight API              TTS Audio Stream
                           │                            │
                     VS Code Editor              Browser AudioContext

🧩 Key Components

📁 Project Structure

code-explainer/
├── 📄 SKILL.md                      # AI agent skill instructions
├── 🔧 setup.sh                      # One-command setup script
├── 📂 scripts/
│   ├── 📡 explainer.sh              # HTTP API helper for the coding agent
│   ├── 🐍 tts_server.py             # Persistent TTS server (Kokoro-82M)
│   ├── 🎙️ podcast.py                # Podcast mode audio generator
│   └── 🔄 reinstall-extension.sh    # Quick extension rebuild
├── 📂 docs/
│   ├── 📖 setup.md                  # Setup reference
│   ├── 🗑️ uninstall.md              # Uninstall guide
│   ├── 🎯 assess.md                 # Preference gathering (depth + delivery mode)
│   ├── 🔍 scan.md                   # Scout sub-agent (file discovery + call chain)
│   ├── 📋 plan.md                   # Planner sub-agent (narrative + transition objects)
│   ├── ⚡ segments.md               # Parallel segment agents (highlight generation)
│   ├── 🎥 walkthrough.md            # Walkthrough mode (sidebar + TTS)
│   ├── 📝 read.md                   # Read mode (text in terminal)
│   ├── 🎙️ podcast.md               # Podcast mode (single audio file)
│   └── 🗣️ tts.md                   # TTS reference (voices, speeds)
└── 📂 vscode-extension/
    ├── 📦 package.json
    ├── ⚙️ tsconfig.json
    ├── 📂 src/
    │   ├── 🚀 extension.ts          # Main entry point
    │   ├── 🌐 server.ts             # HTTP + WebSocket server
    │   ├── 🪟 sidebar.ts            # Webview sidebar provider
    │   ├── 🔄 walkthrough.ts        # Walkthrough state machine
    │   ├── 🎯 highlight.ts          # Code highlighting
    │   ├── 🔊 tts-bridge.ts         # TTS audio streaming
    │   ├── 💾 storage.ts            # Walkthrough persistence
    │   └── 📝 types.ts              # Message protocol types
    └── 📂 media/
        ├── 🎨 icon.svg
        ├── 🖼️ icon.png
        └── 📜 sidebar.js            # Sidebar webview script

📄 License

MIT