MergeStory Install
New$0 per video, by design

Every change has a story.

MergeStory turns a pull request into a short narrated video. What changed, why, and what to review.

Free, open source, and it runs on your machine.

Install Watch the film
Play the film (opens YouTube)
Watch on YouTube (opens a new tab)

Install it with one command.

Pick the way you work. Then run mergestory doctor to check your setup.

Install
npm
npm install -g mergestory

Paste it into your terminal. Then run mergestory doctor.

New to the terminal?

You need Node.js 22.12 or newer, git, FFmpeg, and Google Chrome or another Chromium browser. Open a terminal, paste the line and press Return. mergestory doctor then tells you what is missing and how to fix it. See the three steps.

Works with Claude Code, Codex, GitHub Copilot, Cursor and more. Or use it on its own.

At a glance

  • Free.No paid service is called by default.
  • Local.Voice and rendering run on your machine.
  • Private.Nothing leaves unless you set it up.
  • Grounded.Every line cites the code.
  • Open source.Apache-2.0 licence.

A big pull request is hard to read. A short video does the first pass.

Without MergeStory

Rebuild the author's thinking.

You open the diff and work out what changed and why. It takes time, and a risky line is easy to miss.

With MergeStory

Watch one short video.

A narrator explains what changed, why, and what to review. You know where to look before you open the diff.

One video. Everything a reviewer needs.

Usually 45 seconds to 3 minutes. You also get captions, a poster image and a watch page.

The big picture

See which parts changed.

Animated diagrams show the components that changed and how they connect. The changed parts stand out.

Under the hood

The real code, line by line.

The important code is highlighted as the narrator explains it. It is read from your repository, never generated.

Before and after

Behaviour, side by side.

Shown only when there is something real to show.

What to review

Know where to look.

Risky or subtle spots, each with a link to the file and line.

Captions

Watch without sound.

Every video comes with captions, as VTT and SRT files.

The watch page

Every claim, linked to the code.

A page next to the video lists the chapters, the review checklist and every claim, with links to the code it is based on.

The pictures here are illustrations. See a real video.

See a real one.

A weather client learns to retry with exponential backoff.

Play the demo (opens YouTube)
Watch on YouTube (opens a new tab)
A weather client learns to retry with exponential backoff. Open the watch page for the chapters, the review checklist and every claim, linked to the code.

Reads. Tells. Checks.

Your coding agent writes the story. The engine checks every claim before it draws a single frame.

  1. AnalyzerReads the pull request or branch and builds an evidence pack.
  2. StoryboardThe script. Your coding agent writes it from the evidence pack.
  3. Grounding checksEvery claim and every line reference is checked.
  4. NarrationA free voice reads the script on your machine.
  5. RendererYour browser draws each frame. FFmpeg encodes the video.
  6. PublishLocal by default. Share it only if you choose.

  1. Your agent already knows the change.

    It made the change, or it reviews it. So it writes the storyboard. Without an agent, MergeStory builds one offline from the analysis.

  2. The engine checks every claim.

    Each narration line must cite evidence from the change. Each line reference must point at real code. Claims nobody can check, like "all tests pass", are removed unless real test results were supplied.

  3. Then it renders, on your machine.

    The same input gives the same video. Code on screen is read from your repository. Simulated visuals are labelled.

$0. By design.

A default run calls no paid service at all. No account. No key for your first video.

per video

  • Storyboard$0

    Written by the coding agent you already use. No extra bill.

  • Voice$0

    Kokoro, an open English voice that runs on your own CPU. Installed once.

  • Rendering$0

    Your own browser draws each frame. FFmpeg encodes.

  • Checks$0

    Every claim and line reference is checked on your machine.

  • Sharing$0

    On your own YouTube channel or Google Drive. A fraction of a cent a month on R2 or S3.

Why it is so cheap.

  • The agent

    The expensive part is already done.

    Understanding the change and writing the story is the costly work. Your coding agent has done it, so it writes the storyboard. No second model reads the whole change again. Its usage is part of the session you already run.

  • Local software

    Everything else is ordinary.

    An open voice model on your CPU, the browser you already have, and FFmpeg. No render farm. No cloud GPU.

  • Opt-in

    Paid services are one setting each.

    You can let a model write the storyboard, or use a cloud voice. The default is the cheapest capable model.

  • Honest

    Every run reports its cost.

    It also lists every outbound transfer: the host, the purpose and the size.

When you want more.

Both are opt-in. These are the built-in prices, checked in November 2026. You can override them in the config.

Opt-in prices
  • --llm anthropicClaude Haiku 5.5 storyboard: usually under $0.01 per video ($0.10 per million input tokens, $0.50 per million output tokens)
  • --tts openaiOpenAI gpt-4o-mini-tts: $18 per million characters, about $0.015 per minute of speech
  • --tts elevenlabsElevenLabs Flash: $40 per million characters
  • --tts elevenlabsElevenLabs v3 and Multilingual v2: $80 per million characters

A 2-minute narration is roughly 1,600 characters.

A $0.25 budget, checked before every paid call.

No paid call can take a run over its budget. A model with an unknown price is counted at the highest rate, so the budget still holds. Change it with --budget.

Play the cost film (opens YouTube)
Watch on YouTube (opens a new tab)

How the cost works

Three steps.

Or ask your agent: "explain this pull request as a video".

  1. Install it.

    npm install -g mergestory

  2. Check your setup.

    mergestory doctor lists anything missing, with a fix for each.

  3. Make a video.

    mergestory generate <pull request URL>

You need Node.js 22.12 or newer, git, FFmpeg, and Google Chrome or another Chromium browser. No pull request? Run mergestory generate . --base main --head feature/retry on a local branch. It works with every git host. Add --dry-run to see the plan, the cost estimate and what would leave your machine, without rendering.

Quality presets: draft is 1280x720 at 24 fps. Standard, the default, is 1920x1080 at 30 fps. High is 1920x1080 at 60 fps.

Will it work with your agent?

MergeStory is an Agent Skill. Install it in the place your agent reads.

Claude Code

Install the plugin from inside Claude Code 2.1.275 or newer.

/plugin install mergestory --marketplace PiniShv/MergeStory

On an older version: /plugin marketplace add PiniShv/MergeStory, then /plugin install mergestory@mergestory. Or copy the skill to ~/.claude/skills/mergestory.

Many agents, one command

Needs Node.js 22.20 or newer.

npx skills add PiniShv/MergeStory

A shared skills folder

Copy plugins/mergestory/skills/mergestory to .agents/skills/mergestory for one project, or ~/.agents/skills/mergestory for all projects.

  • Codex
  • GitHub Copilot
  • Cursor
  • OpenCode
  • Goose
  • Amp
  • Gemini CLI
  • Antigravity

Copilot also reads .github/skills. Cursor also reads .cursor/skills.

GitHub CLI

Needs GitHub CLI 2.90 or newer.

gh skill install PiniShv/MergeStory mergestory

Their own folders

Copy the same skill folder here.

  • Windsurf: .devin/skills/mergestory
  • Kiro: .kiro/skills/mergestory
  • Cline: .cline/skills/mergestory

No agent? No problem.

The engine works on its own. Use it from the command line, over an HTTP API, as a library, or in GitHub Actions.

  • CLI
  • HTTP API
  • Library
  • GitHub Actions

With the skill, the agent writes the storyboard itself from MergeStory's evidence pack. The skill runs the mergestory command, and asks before it installs it. The engine still checks every claim and every line reference before rendering. Windsurf is now Devin Desktop. Gemini CLI and Google's Antigravity CLI both read .agents/skills.

Private by default.

Your code stays on your machine unless you decide otherwise.

  • Telemetry

    No telemetry.

    MergeStory does not report what you do or what you make.

  • Your code

    Nothing leaves unless you set it up.

    Nothing from your code or the change goes anywhere until you turn on a model, a cloud voice or an upload. The only download is the free voice, once. It sends nothing from the change.

  • Sensitive files

    Never shown, never sent.

    Files like .env, keys and credentials are left out of every video.

  • Secrets

    Masked everywhere.

    Secrets and e-mail addresses are masked in every frame, caption and log.

  • Links

    Links you control.

    Private S3 links stop working after 7 days at most. Google Drive and YouTube links do not expire. Public links for a private repository are blocked unless you allow them.

  • Your repository

    Read-only.

    MergeStory never changes your repository or its git state.

Check it yourself.

Run any command with --dry-run. It shows the plan, the cost estimate and what would leave your machine, and renders nothing.

Or read the code. MergeStory is open source under the Apache-2.0 licence. Read it on GitHub. Security policy

mergestory generate <pull request URL> --dry-run

Share it when you are ready.

A video stays on your machine until you choose to share it.

Know before you install

One catch: the first video takes longer.

The first English video installs the free voice once. That is about 400 MB, then the voice model, so it takes a minute or two longer. Nothing from the change is sent.

  • Do it ahead of time. Run mergestory setup kokoro, for example in CI.
  • It needs FFmpeg and a browser. Google Chrome or another Chromium browser draws the frames.
  • The free voice speaks English. The offline storyboard is English only too.
  • Node.js22.12 or newer
  • gitto read the change
  • FFmpegto encode the video
  • A browserChrome or another Chromium
  • The free voiceabout 400 MB, once
mergestory doctor checks all of this. Get started in the README

What MergeStory is not

  • Not a reviewer. It points to what to review. You decide.
  • Not a service. There is no account. It runs on your machine.
  • Not free in every language. The free voice is English only.
  • Not a cheerleader. Claims it cannot check are removed.

Questions before you install.

Short answers. The documentation has the rest.

Does my code leave my machine?

Not by default. The analysis, the checks, the voice and the rendering all run on your machine. There is no telemetry.

Something leaves only if you turn it on: a model that writes the storyboard, a cloud voice, or an upload. Run --dry-run to see what would leave. Your coding agent already sees the change in your session. MergeStory adds no other service.

What does it cost?

$0 per video by default. No paid service is called. If you opt in to a model for the storyboard, Claude Haiku 5.5 usually costs under $0.01 per video. Cloud voices are priced per million characters. A budget of $0.25 per run is checked before every paid call. See the full cost.

Which agents does it work with?

It is an Agent Skill for Claude Code, Codex, GitHub Copilot, Cursor, OpenCode, Goose, Amp, Gemini CLI, Windsurf, Kiro and Cline. See where each one reads it from.

Can I use it without an agent?

Yes. Run mergestory generate on a pull request URL or a local branch. Without an agent, it builds the storyboard offline from the analysis. You can also use the HTTP API or the library.

Where do the videos go?

They stay on your machine. You get an MP4 video, captions (VTT and SRT), a poster image and a local watch page. Share one when you are happy with it: YouTube, Google Drive, S3-compatible storage, or a comment on the pull request.

Is the narration accurate?

Every narration line cites evidence from the change, and the code on screen is read from your repository. Claims nobody can check, like "all tests pass", are removed unless real test results were supplied. The checks run on your machine before rendering.

It checks claims against the change. It cannot judge whether the change is a good idea, so use the review checklist as a starting point.

Can I run it in CI?

Yes. The GitHub Actions example makes a video when a maintainer adds a label to a pull request. It uploads the video to your own storage and posts one comment with the link. Read the guide.

What does it need?

Node.js 22.12 or newer, git, FFmpeg, and Google Chrome or another Chromium browser. The first English video also installs the free voice once, about 400 MB plus the voice model. Run mergestory doctor to check.

Every change has a story.

Reads. Tells. Checks. Free, on your machine.

Install MergeStory and turn your next pull request into a video.

Install
npm install -g mergestory
/plugin install mergestory --marketplace PiniShv/MergeStory

Use npm in a terminal, or the second line inside Claude Code. Then run mergestory doctor.

Read the code on GitHub · All install options · Watch page demo