ncrispino/reelplanner

Your agent turns its plan into a short narrated video that stops at each open choice and asks you. You answer on the video, and the agent updates the plan.

Works with: Claude Code (tested) · Codex CLI (tested on macOS; features and evidence) · GitHub Copilot, Cursor, OpenCode, Antigravity CLI (untested: what each needs)

Before you try

• macOS (Homebrew) or Linux (apt), Node 22.20+ (nodejs.org; apt's own nodejs is older), and Python 3.10+ for the local voice. Setup may ask for sudo. Windows: not yet (WSL untested).
• About 1 GB in all: the package (about 64 MB, mostly reelplanner's own plans and the sample videos it ships with), then setup's headless Chrome and a one-time 840 MB of voice and caption models.
• reelplanner sends none of your code anywhere; an optional hosted voice gets only the narration text.

Install

npm i -g github:ncrispino/reelplanner                                  # the `reelplanner` command
reelplanner setup                                                      # ffmpeg, Chrome, a local voice (--dry-run to preview)
npx skills add "$(npm root -g)/reelplanner" --skill plan-to-video -g -y   # the skill, for every agent found

In Claude Code, the skill can come as a plugin instead of the third line, kept up to date through /plugin:

/plugin marketplace add ncrispino/reelplanner
/plugin install reelplanner@reelplanner

Codex has a native plugin route too, using the package installed by the first line:

codex plugin marketplace add "$(npm root -g)/reelplanner"
codex plugin add reelplanner@reelplanner

Codex keeps its own copy of the plugin: after updating reelplanner, run the second line again. In Codex, start with $plan-to-video <plan.md>, or ask it to make a plan with reelplanner. See Codex setup and tested features for details.

Both plugins install the skill: the first two lines are still what install the reelplanner command and its tools (the skill installs them itself when they are missing, but running them first is quicker).

The narration needs a voice. Choose one before you run reelplanner setup:

• Local (the default): free, and nothing leaves your machine. Setup downloads about 840 MB of voice and caption models once, and it needs Python 3.10+. On a slow machine it takes minutes per line.
• Hosted: nothing to download, 1–3 seconds a line, about $0.03 a minute of narration with your own OpenRouter key. Run reelplanner setup --hosted-voice instead: it skips the local voice and prints two lines to put in ~/.reelplanner/.env (the voice says more).

In Claude Code, allow its commands once, so each step runs without a prompt.

The skill goes in ~/.agents/skills, linked into ~/.claude/skills and other agents' folders. Trouble or uninstalling: install details. Installed it before as reelplanning, its name until October 2026? Run npm rm -g reelplanning first: npm will not install over its commands (moving over).

Quick start

Run these in a terminal, or type the quoted text into your agent's chat.

A project you already have: in its folder, ask for the next change as a plan.

cd my-app
claude "Use reelplanner to plan adding dark mode"

Nothing in the project has to change first: the agent reads the code that is there and plans with its names. If you keep a record (ways 2 and 3), it also maps the project's parts into .reelplanner/ as it plans. Two more ways in, from the same folder:

claude "Make a video of the plan in docs/plan.md"              # a plan you already wrote
claude "Make a quick video explaining how src/auth works"      # code that is already there

A new project, from an empty folder:

mkdir bakery-site && cd bakery-site && git init
claude "Use reelplanner to plan a small website for a neighborhood bakery"

The first time in a repo, the agent asks how much you want: just a video, or more (three ways). Say "quick" in the request ("make a quick video plan for …") to skip the question and get just the video.

In Codex, the same with codex "…". In Copilot, Cursor and other agents, add "with the plan-to-video skill" to the request (what each needs).

What happens

• The agent writes the plan and makes a narrated video of it, in videos/<name>/. Building the video takes minutes; how many depends mostly on the voice (see The voice).
• The video opens in your browser and stops at each open question. Pick an answer, or write your own.
• Comment on any moment, then press Finish review and Send: the review goes to the agent, which updates the plan. The local page saves directly; you do not need to download a file. A disconnected portable copy exports a review file to return to the agent.
  • For a quick video, nothing is added to the repo: the review waits on your machine, in ~/.reelplanner/inbox/, until the agent picks it up. If no agent session is waiting, tell it the review is sent.
  • Otherwise, the agent also keeps the review in a .reelplanner/ folder in the repo (see three ways).

Three ways to use it

1. Just a video. A plan video, or a video explaining code that is already there.
2. Plus a walkthrough. After the agent builds the plan, a walkthrough video of what was built: the change running. It stops at the choices the agent made on its own that you'd notice or can't easily undo, and lists the rest at the end.
3. Everything recorded. Your answers are kept in the repo and later plans must follow them. One overview video of the whole project is updated as changes land.

Ways 2 and 3 add a .reelplanner/ folder to the repo (commit it). The first time in a repo, the agent asks which way you want, unless you said "quick". To move to a fuller way later, ask the agent. How it fits together.

Review beside your agent in the terminal

Ask your agent to open a video's review "beside me in the terminal". It opens in a split next to the agent. Watch, answer, comment and press Send: the split closes, the agent wakes with your review and gets to work, and when the new version is built it opens beside you again. You never leave the terminal or tell the agent it was sent.

Your agent's own permissions still apply while it works. In our Linux trial, Codex on its default settings asked you to approve 15 of its commands between Send and the new version (where it keeps the review, the build and its checks, git, reopening the split); 9 in a repo set up with reel init, where the review is kept in the repo. Codex's "Approve for me" setting decides them for you instead. Claude Code in auto mode, with reelplanner's commands allowed (Claude Code), asked none.

Set it up once, from your own terminal (not inside an agent). Install terminal-browser, then remember the workspace:

brew install --cask terminal-browser          # macOS (Linux: curl -fsSL https://terminal-browser.sh/install | bash)
reelplanner review-setup --workspace terminal-browser                       # Claude Code and other agents
reelplanner review-setup --workspace terminal-browser --codex-allow-open    # Codex: it also opens reviews with no prompt

Restart Codex afterwards. Tested with Codex and Claude Code, in Ghostty on macOS and in tmux (in Ghostty) on Linux, where the split is a new tmux pane beside the agent's. reelplanner review-setup --check checks the setup; --codex-disable-open removes Codex's rule; --workspace browser goes back to your ordinary browser, the default. With Codex, start the session with a model Codex does not mark as cyber (codex -m <model>): for those, Codex ignores the saved rule, and you open the link yourself. Details: terminal review.

Security: what you allow. Read this before you set it up.

• Codex runs the opener outside its sandbox, without asking. --codex-allow-open saves a Codex rule for one command, reelplanner's review-open. It reads your process list to find the Codex window, reads that window's terminal settings, and opens a local review page beside it. It starts no server and sends nothing.
• Your terminal may be scripted. On macOS, the first split asks you to let Codex (or your terminal) control Ghostty. That permission is broad: a program run with it can type into any Ghostty window. reelplanner uses it only to split, and to close its own split with Ctrl+Q after Send, but the permission is not limited to that.
• Send wakes your agent. The review server listens on 127.0.0.1 only, but any program running as you on this machine can post a "review" to it, and a waiting agent will start working on it with nobody typing. The review is passed as data, not as instructions, yet it still reaches your agent. Use it on a machine you trust, and stop the server when you are not reviewing: reelplanner review --stop.
• The server runs outside the sandbox. Starting it needs one approval in Codex: it writes its log and your review outside the workspace.

Case studies

Real projects built with reelplanner, each with its videos, reviews and session: reelplanner-case-studies (browse them).

• A Bob Dylan site: an interactive site about Bob Dylan's life and music, from an empty folder through four plans; seven videos, each reviewed.

Why, and how it compares

Agents write plans faster than people can read them. A long plan gets skimmed, and the choices in it go unseen. The original name, reelplanning, sounded like “real planning”: watching a plan makes long proposals easier to understand.

"The output format I am most bullish on is fully custom / bespoke explainer videos generated on any arbitrary topic." — Andrej Karpathy, on X, October 2026

Spec Kit is far more widely used, and for a one-line fix or a plan you can read in a minute, text is faster. More tools, with sources: docs/comparison.md.

How it works

reelplanner is an agent skill plus two commands: reelplanner (setup and videos) and reel (the .reelplanner/ record). Each scene is a web page rendered with HyperFrames; everything is kept as text, so any video can be rebuilt.

This repo is planned with reelplanner: its own plans are in .reelplanner/plans/. More: how it fits together · the .reelplanner/ folder · every command · what works today.

The voice

By default the narration is made on your machine, free and private: a local voice (Kokoro) reads the script and whisper.cpp times the captions. Nothing to sign up for, and nothing leaves your machine. It costs about 840 MB of models, downloaded once, and needs Python 3.10+.

On a slow machine that can take minutes per line, so reelplanner setup times one line and tells you if it is too slow here. If it is, or you would rather not install the local voice at all, use a hosted voice through OpenRouter:

• Faster: 1–3 seconds a line.
• Nothing to install: no voice models to download, no Python.
• Costs about $0.03 per minute of narration, paid with your own OpenRouter account and API key.
• Sends the narration text (not your code) to OpenRouter.

To switch, put these two lines in ~/.reelplanner/.env (one file for every repo on this machine, outside any repo, so it is never committed), then run reelplanner narration-check to hear a test line:

REELPLANNER_TTS=openrouter
OPENROUTER_API_KEY=sk-or-…

Once the two lines are there, setup skips the local voice and says so; reelplanner setup --hosted-voice skips it even before you add them. To go back to the local voice, delete the two lines and run reelplanner setup.

Other providers, or a key for one repo only: narration engines.

Contributing

Start with an issue for a bug or an idea; a pull request links the issue it fixes. Setup and tests: CONTRIBUTING.md.

Where help is most welcome:

• The bigger ideas: live feedback while you watch, spoken comments, reviewing from the terminal, and learning from your edits (what's next).
• More agents: making it work as well in Codex, Copilot, Cursor and others as in Claude Code (what each needs).

Where this is going

Our goal is for people and AI to work well together, with people able to follow what an agent plans and does, and to steer it, in a form that is easier to take in than code.

As agents grow more capable, people will read less and less of the code agents write. So two things matter more and more: understanding reliably what is happening, and giving feedback with as little friction as possible.

Video is our first step on both. We plan to keep improving each.

License

Apache-2.0. See NOTICE.