code-explainer - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #llm #go #nodejs #windows #cli #awesome-list #vue #security #mcp #ios #openai

code-explainer

(★ 88)

Interactive code walkthrough skill with VS Code highlighting and AI-powered voice narration

파일 탐색기

최종 버전 다운로드 (.zip)

- - 2026-03-06-sharing-walkthroughs-design.md
  - 2026-03-06-sharing-walkthroughs-plan.md
- assess.md
- cover.png
- plan.md
- podcast.md
- read.md
- scan.md
- segments.md
- setup.md
- tts.md
- uninstall.md
- walkthrough.md
- explainer.sh
- podcast.py
- reinstall-extension.sh
- tts_server.py
- - icon.png
  - icon.svg
  - sidebar.css
  - sidebar.js
- - extension.ts
  - highlight.ts
  - server.ts
  - sidebar.ts
  - storage.ts
  - tts-bridge.ts
  - types.ts
  - walkthrough.ts
- .vscodeignore
- LICENSE
- package-lock.json
- package.json
- README.md
- tsconfig.json
.gitignore
LICENSE
README.md
setup.sh
SKILL.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/Royal-lobster/code-explainer

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd code-explainer

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

cd vscode-extension

이 프로젝트의 관련 파일이 하위 폴더 안에 있어서, 먼저 그 폴더로 이동합니다.

npm install

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm start

개발/실행 서버를 켭니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <img src="vscode-extension/media/icon.png" width="120" height="120" alt="Code Explainer icon" />
</p>

<h1 align="center">Code Explainer</h1>

<p align="center">
  <strong>✨ Interactive code walkthroughs with editor highlighting and AI-powered voice narration.</strong>
</p>

<p align="center">
  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.
</p>

<p align="center">
  <img src="docs/cover.png" alt="Code Explainer cover" width="100%" />
</p>

<p align="center">
  <a href="https://youtu.be/3eX4hGW9ym8">🎬 Watch Demo</a> &nbsp;·&nbsp;
  <a href="https://srujangurram.me/blog/code-explainer">📝 Read Writeup</a>
</p>

---

## 🚀 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.

<details>
<summary>📋 Manual installation</summary>

### Skill-native agents

These agents support the `skills/<name>/SKILL.md` format natively. Clone directly into the skills directory:

| Agent | Install commands |
|-------|-----------------|
| **Claude Code** | `git clone https://github.com/Royal-lobster/code-explainer.git ~/.claude/skills/explainer` |
| **Amp** | `git clone https://github.com/Royal-lobster/code-explainer.git ~/.config/agents/skills/explainer` |
| **OpenCode** | `git clone https://github.com/Royal-lobster/code-explainer.git ~/.config/opencode/skills/explainer` |
| **Codex CLI** | `git clone https://github.com/Royal-lobster/code-explainer.git ~/.codex/skills/explainer` |

Then run setup:

```bash
<SKILLS_DIR>/explainer/setup.sh
# Reload your editor: Cmd+Shift+P → "Developer: Reload Window"
```

### Rule-based agents

These agents use their own rules/instructions format. Clone to any location, run setup, then point your agent's rules at the `SKILL.md`:

```bash
# 1. Clone to a shared location
git clone https://github.com/Royal-lobster/code-explainer.git ~/code-explainer

# 2. Run setup
~/code-explainer/setup.sh

# 3. Reload your editor: Cmd+Shift+P → "Developer: Reload Window"
```

Then add a rule or instruction pointing to the skill:

| Agent | How to add |
|-------|------------|
| **Cursor** | Add a `.cursor/rules/explainer.mdc` file in your project that includes the contents of `SKILL.md` |
| **Windsurf** | Append the contents of `SKILL.md` to `~/.codeium/windsurf/memories/global_rules.md` |
| **Kilo Code** | Copy `SKILL.md` to `~/.kilocode/rules/explainer.md` |
| **Roo Code** | Copy `SKILL.md` to `~/.roo/rules/explainer.md` |
| **Cline** | Copy `SKILL.md` to your `.clinerules/explainer.md` directory |

> **Note:** The `SKILL.md` references relative paths (e.g., `docs/assess.md`), so the full repo must exist at the cloned location. For rule-based agents, ensure paths in the copied rules resolve correctly or use absolute paths.

### What setup.sh does

- 🐍 Python venv creation with TTS engine (mlx-audio + sounddevice)
- 🧩 VS Code extension build and installation (.vsix for VS Code + Cursor)
- 🗣️ Voice model download (~330 MB)
- 🔑 Script permissions

</details>

## 💬 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

| Mode | Description |
|------|-------------|
| 🎥 **Walkthrough** | Highlights move through code automatically while voice narrates in sync. Hands-free — just watch and listen. |
| 📝 **Read** | Text explanations in terminal. Highlights code, explains in text, waits for "next". No sidebar or TTS required. |
| 🎙️ **Podcast** | Generates a single audio file of the entire walkthrough. Listen anywhere. |

### 🪟 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:

```bash
# 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:

| Shortcut | Action |
|----------|--------|
| `Ctrl+Shift+Space` | Toggle play / pause |
| `Ctrl+Shift+]` | Next sub-segment |
| `Ctrl+Shift+[` | Previous sub-segment |
| `Ctrl+Shift+Alt+]` | Next segment |
| `Ctrl+Shift+Alt+[` | Previous segment |
| `Ctrl+Shift+\` | Stop walkthrough |
| `Ctrl+Shift+=` | Speed up TTS |
| `Ctrl+Shift+-` | Speed down TTS |

### 💬 Text Controls

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

| Command | Action |
|---------|--------|
| `next` | ⏭️ Move to next segment |
| `skip` | ⏩ Skip current segment |
| `skip to 4` | 🎯 Jump to segment 4 |
| `pause` | ⏸️ Pause walkthrough |
| `mute` / `unmute` | 🔇 Toggle voice narration |
| `stop` | ⏹️ End walkthrough |

## 🗣️ Voice Configuration

Code Explainer uses [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [mlx-audio](https://github.com/Blaizzy/mlx-audio) for high-quality local TTS. Falls back to macOS `say` if unavailable.

```bash
# Change voice
export TTS_VOICE=am_adam    # American male

# Change speed
export TTS_SPEED=1.2        # 20% faster
```

### 🎤 Available Voices

| Voice | Description |
|-------|-------------|
| `af_heart` | 🇺🇸 American English, female (default) |
| `af_bella` | 🇺🇸 American English, female |
| `af_sarah` | 🇺🇸 American English, female |
| `am_adam` | 🇺🇸 American English, male |
| `am_michael` | 🇺🇸 American English, male |
| `bf_emma` | 🇬🇧 British English, female |
| `bm_george` | 🇬🇧 British English, male |

## 🏗️ 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

| Component | Description |
|-----------|-------------|
| 🌐 **Extension Server** (`server.ts`) | HTTP + WebSocket server with bearer token auth. Endpoints for plan delivery, state queries, save/load, and long-polling user actions. |
| 🪟 **Sidebar** (`sidebar.ts`) | Webview panel showing the walkthrough — segment list, per-highlight explanations, and playback controls. |
| 🔄 **Walkthrough** (`walkthrough.ts`) | State machine managing segment and sub-highlight navigation and playback status. |
| 🎯 **Highlight** (`highlight.ts`) | Opens files, scrolls to ranges, and applies gold background decorations. |
| 🔊 **TTS Bridge** (`tts-bridge.ts`) | Streams audio from the Python TTS server to the sidebar webview via WebSocket. |
| 🐍 **TTS Server** (`tts_server.py`) | Persistent Python daemon that loads Kokoro once and streams audio over a Unix socket. |
| 💾 **Storage** (`storage.ts`) | Save and load walkthroughs as `.walkthrough.json` files for replay and sharing. |
| 📡 **Helper Script** (`explainer.sh`) | CLI wrapper around the HTTP API — used by the coding agent to send plans and poll for user actions. |

## 📁 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