codebase-video

Ask Claude Code for a video about your code. Get a narrated video that explains it.

Every statement in the video is checked against your code before the video is made.

https://github.com/user-attachments/assets/98c04504-aac9-43aa-afda-cc8d9962a076

This video was made by the plugin, about the plugin.

What is it?

A plugin for Claude Code. You point it at a folder of code. It reads the code
and makes a video in which a voice explains how the code works, with diagrams and the real code on screen.

Each chapter that follows a path through the code opens on one map of the project's main parts, with that path lit
up, and the video zooms into a part when it goes inside it, so you always know where you are.

People use it to:

• help a new teammate understand a project;
• understand a project somebody else wrote;
• explain one part of a big system.

How do I use it?

1. Install three things (if you do not have them yet):

• Node.js (version 22.12 or newer)
• ffmpeg, with its x264, VP9 and Opus encoders (Homebrew's ffmpeg has them, and so do the usual
  Linux packages)
• Google Chrome (or Chromium)

On a Mac: brew install node ffmpeg. On Linux, take Node.js from nodejs.org: the one most
distributions ship is older than 22.12.

2. Add the plugin. Type these two lines in Claude Code:

/plugin marketplace add OnurGumus/codebase-video
/plugin install codebase-video@codebase-video

3. Ask for a video. Open Claude Code in the folder with your code and type:

/codebase-video

Claude asks what the video should cover, how long it should be, and who will watch it. Then it does the work.
You do not need to stay and watch.

The first time, the plugin sets itself up: it checks that the three things above are there (and says how to install
any that is missing), then downloads about 800 MB, mostly the voice. This happens only once.

What do I get?

A video file (.mp4) with captions, saved inside your project in a folder called .codebase-video.

Your code is not changed. Git ignores that folder, so nothing is committed by accident.

Can it show what changed?

Yes. Ask for a progress video: "make a progress video since v1.4.0", or since a commit or a date. It shows what
shipped in that range, where the work went, and what is still open, for someone who follows the project and does
not read its code every day. Every number in it is read from git by a program. It names no one unless you ask it
to, and it reports what changed without judging the team.

It can also run without questions from CI, on each release or once a week: see docs/ci.md.

How long does it take, and what does it cost?

You pick the length of the video:

These times are rough, and it is the computer's time, not yours: you can do something else meanwhile.

How much of my Claude plan does it use? It is not light, because most of the work is checking. The helper
agents use roughly:

The measured rows come from two small projects. The estimates are worked out from the number of agents each
length needs and how much each one reads; adding one chapter to an existing tour used about 1.5 million, which
fits. Three things move these numbers: a bigger project costs more, because there is more to read and check;
every round of fixes after a check adds some; and the main Claude session adds some on top.

Most of the tokens are Claude reading your code and its own drafts. Drawing and encoding the video happen on your
computer and use no tokens.

Not sure yet? Ask for a preview first. You get the checked write-up of your code and the narration to listen
to, without the pictures. It is much quicker and cheaper, and if you like it, Claude carries on from there to the
full video without redoing anything.

Changing a video afterwards is quick. Only the scenes that changed are drawn again: about a minute for a
changed picture or sentence in a five-minute video, where drawing the whole video takes about five.

The first time, the plugin downloads about 800 MB, mostly the voice. This happens only once.

Is what the video says correct?

A video that explains code wrongly is worse than no video, so that is what most of the work goes into. Before anything is drawn, Claude writes down what it learned and notes
the exact file and line behind every statement. Then a second Claude, which has not seen the first one's work,
checks each statement against your code. The script and the pictures are checked the same way.

Here is what the checks caught while making the five-minute video at the top of this page:

Two kinds of checking are at work. A program checks what a program can: that every picture appears on the words
that describe it, that nothing overlaps or flashes by too fast, that no number is shown that the write-up does
not contain. Whether an explanation is right is checked by Claude, against the code, by a Claude that did not
write it. That is careful checking, not a proof: if something in a video looks wrong, the write-up next to it
tells you the file and line to look at.

More detail: how it works.

Is my code private?

• The voice, the drawing and the video files stay on your computer. The video is not uploaded anywhere.
• Your source code is read by Claude Code, the same as whenever you use Claude Code. The plugin does not make
  your code more private than Claude Code already is.
• Claude is told to keep passwords and keys out of the video, and checks for them.
• The video shows your code. Share it only with people who may see the code.

Common questions

Which programming languages work? All of them. Claude reads whatever is in the folder. Code on screen is
coloured for F#, C#, JavaScript, TypeScript, Python, SQL, JSON, YAML, Bash, Nix and Dockerfiles; other languages
are shown in one colour.

Can I change the video afterwards? Yes. Tell Claude what to change, for example "chapter 2 is too fast". Only
the scenes that changed are drawn again, so a small fix takes about a minute, not the whole render.

Can I give it hints? Yes. Say them when you ask: what to cover, what to leave out, who will watch, what to check
extra carefully. For hints that should apply to every video of a project (your team's terms, parts to always
skip), put them in a file named .codebase-video/hints.md in that project. Claude will offer to save them for you.

Can I put the video in my README? Yes, a short one. GitHub plays a video inside a README only up to 10 MB, so
short videos are kept under that, and their first frame is drawn as a thumbnail with a play button, like the one
at the top of this page. Edit your README on github.com and drag the .mp4 into the editor.

Does the video have captions? You always get a separate captions file (.vtt) that video players can load. If
you want the words drawn into the picture itself, for example for a README, where the player starts muted, ask for
"captions in the video". They are off unless you ask.

Can I present it in my own voice? Yes. Ask for "a deck to present it myself". You get a PowerPoint file
(.pptx, which Keynote, Google Slides and LibreOffice also open) with one slide per sentence and that sentence as
the speaker note, the script with a timestamp on each line, subtitles (.srt), and the video without its sound. You
can ask for the slides to move: each slide then plays its part of the animation as it opens (in PowerPoint and
Keynote; other apps show a still). Or ask for the click-through version: the animated video in your browser, where
each click plays the next step and waits for you.

Do I need Python or .NET? No.

Does the voice need an account or a key? No. The voice runs on your computer.

Want to help build it?

See CONTRIBUTING.md. The plugin is written in F#.

License

MIT. See LICENSE.