io.github.alichherawalla/video-overlay-kit

Make b-roll for your videos. Tell an agent what you want. Get an MP4 back.

Zero per-render cost. Wednesday Solutions design system as the default theme. Built for people who ship a lot of short-form video and don't want to learn After Effects. Works with any MCP-compatible agent — Claude Code, Codex, OpenCode, Cursor, Cline, or anything else that speaks the Model Context Protocol.

Same scene spec, both orientations. Portrait fits TikTok / Instagram Reels / YouTube Shorts. Landscape fits YouTube / desktop / TV. The kit auto-flips the layout based on the canvas aspect.

list-reveal · a title and three points appearing on cue

_{Portrait <a href="examples/list-reveal.json">spec</a> · <a href="examples/list-reveal.mp4">mp4</a>   •   Landscape <a href="examples/list-reveal-landscape.json">spec</a> · <a href="examples/list-reveal-landscape.mp4">mp4</a>}

flow · a process from A to B to C

_{Portrait <a href="examples/flow.json">spec</a> · <a href="examples/flow.mp4">mp4</a>   •   Landscape <a href="examples/flow-landscape.json">spec</a> · <a href="examples/flow-landscape.mp4">mp4</a>}

comparison · two things in contrast

_{Portrait <a href="examples/comparison.json">spec</a> · <a href="examples/comparison.mp4">mp4</a>   •   Landscape <a href="examples/comparison-landscape.json">spec</a> · <a href="examples/comparison-landscape.mp4">mp4</a>}

hub · a centre concept with satellites pointing in

_{Portrait <a href="examples/hub.json">spec</a> · <a href="examples/hub.mp4">mp4</a>   •   Landscape <a href="examples/hub-landscape.json">spec</a> · <a href="examples/hub-landscape.mp4">mp4</a>}

Every clip above is real output. 5 to 6 seconds. Wednesday Solutions design system as the default theme. Click any mp4 link for the full-quality version.

Start here

Paste this into a fresh session of any MCP-compatible coding agent (Claude Code, Codex, OpenCode, Cursor, Cline, etc). The agent does the whole setup. It clones the repo, installs deps, wires the MCP into your config, and verifies it works.

Set up github.com/alichherawalla/video-overlay-kit as an MCP server in
my coding agent.

1. Clone the repo to ~/code/video-overlay-kit (or ask me where to put it
   if that path is taken).
2. Run `npm install` inside the cloned directory.
3. Find my MCP config file and add a `video-overlay-kit` entry that runs
   `node <absolute-cloned-path>/bin/mcp.mjs`. Pick the right path for my
   agent:
     - Claude Code: `.mcp.json` in the current repo, otherwise
       `~/.claude/mcp_settings.json`.
     - Codex / OpenCode: their MCP config (usually `~/.codex/mcp.json`
       or similar — ask me if you can't find it).
     - Cursor / Cline: their MCP settings in the IDE config.
   Preserve any existing MCP servers in the config.
4. Verify the server starts by sending it a `tools/list` JSON-RPC request
   over stdio and confirming the tools `list_icons`, `validate_scene`, and
   `render_scene` come back.
5. Tell me to restart my agent so the new MCP server is picked up.

After setup, read the README at the cloned repo so you know how to author
scene specs. Default to the Wednesday Solutions light theme and 5-second
duration unless I say otherwise.

Restart Claude Code. Now ask for a video:

"Make me a 5-second overlay titled 'A runbook for every incident' with three rows: drift, prompt injection, exfil attempts."

The agent picks the icons, writes the scene spec, renders the MP4, hands you the file path. Drop it into your editor.

If you want to wire the MCP yourself instead, skip to Manual setup.

What you can make

Eight building blocks. Combine any of them inside a single 4-to-6-second scene.

title-overlay

The deliverable bar at the top of the frame. Use this on every scene. It is the one-line promise of what the viewer is about to see.

If a stranger reads the title and can't immediately tell what the video is about, rewrite it.

The bar lives at the top of the frame with a thin lavender accent underneath. 80pt bold, centered. You don't pick the position, it is fixed.

{ "kind": "title-overlay", "id": "agenda",
  "text": "How to control AI traffic",
  "startFrame": 0, "endFrame": 150 }

list-reveal

A vertical list of 1 to 5 rows. Each row gets an optional icon and reveals on a frame you specify.

Use this when you have a list of things to show, between 1 and 5 of them.

{ "kind": "list-reveal", "id": "outcomes",
  "position": { "x": 0.5, "y": 0.55 },
  "startFrame": 20, "endFrame": 150,
  "rows": [
    { "text": "One gateway in front of every model",          "iconName": "IconShield",   "revealAtFrame":  0 },
    { "text": "Input policy. Output policy.",                 "iconName": "IconFilter",   "revealAtFrame": 35 },
    { "text": "Every prompt, every dollar, every output",     "iconName": "IconChartBar", "revealAtFrame": 70 }
  ]
}

flow

A horizontal sequence of 2 to 5 nodes. Each node appears, an arrow draws toward the next one, the next node appears.

Use this when the meaning is in the sequence. Incident detected leads to runbook activated leads to contained.

{ "kind": "flow", "id": "incident-flow",
  "startFrame": 20, "endFrame": 150,
  "nodes": [
    { "iconName": "IconAlertOctagon", "label": "Incident" },
    { "iconName": "IconBook2",        "label": "Runbook" },
    { "iconName": "IconCircleCheck",  "label": "Contained" }
  ]
}

comparison

Two icons side by side with a configurable divider in the middle. Each side has a label and an optional sub-label.

Use this for binary contrasts. Old way against new way is the canonical example.

The divider word is configurable. "vs" is the default for opposition; swap to "+" or "→" when the relationship is additive or transitional.

{ "kind": "comparison", "id": "old-vs-new",
  "startFrame": 20, "endFrame": 180,
  "left":  { "iconName": "IconClockHour3", "label": "Old way", "subLabel": "Manual review" },
  "right": { "iconName": "IconBolt",       "label": "New way", "subLabel": "Automated checks" },
  "divider": { "label": "vs", "showLine": true }
}

hub

A central icon with 2 to 4 satellites around it. The center appears first, then each satellite reveals with a line drawing in from the center.

Use this when one thing is at the centre and other things hang off it. A gateway that controls policy, logging, cost, and swap is a hub.

{ "kind": "hub", "id": "gateway-hub",
  "startFrame": 20, "endFrame": 150,
  "center": { "iconName": "IconShield", "label": "Gateway" },
  "satellites": [
    { "iconName": "IconLock",     "label": "Policy" },
    { "iconName": "IconActivity", "label": "Logging" },
    { "iconName": "IconCoin",     "label": "Cost" },
    { "iconName": "IconRefresh",  "label": "Swap" }
  ]
}

icon, text, lottie

The escape hatches. Drop a single Tabler icon anywhere on the canvas, a free-position text block, or a pre-animated Lottie animation. Use these when the composite components above don't fit.

{ "kind": "icon", "id": "hero", "name": "IconShieldCheck",
  "position": { "x": 0.5, "y": 0.45 }, "sizePx": 240,
  "startFrame": 10, "endFrame": 150 }

Most users never read the full field reference for these. The agent reads the schema for you. If you want every field listed out, jump to the reference section.

Customize the look

The kit ships with the Wednesday Solutions palette. Lavender accent on a warm off-white canvas. Every scene also gets an ambient bloom gradient behind the tracks and a sunset gradient on the title text by default. This is what "polished" looks like out of the box.

Everything is configurable through the scene spec. You don't edit JSON, you ask the agent in plain language.

The codec auto-switches. Solid backgrounds render as H.264 MP4. The transparent setting renders as ProRes 4444 MOV with a real alpha channel.

If you want to change the default theme for every scene without saying so each time, edit src/scene/theme.ts. The palette is one object. Change the hex values and every component picks them up.

Manual setup

Skip this if you used the one-shot prompt above.

git clone git@github.com:alichherawalla/video-overlay-kit.git
cd video-overlay-kit
npm install

Add the kit to your project's .mcp.json or your global ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "video-overlay-kit": {
      "command": "node",
      "args": ["/absolute/path/to/video-overlay-kit/bin/mcp.mjs"]
    }
  }
}

Restart Claude Code. Three tools appear under video-overlay-kit:

• list_icons(query?, limit?) searches the Tabler library by substring. About 5,000 line icons.
• validate_scene(spec) runs the schema check before render.
• render_scene(spec, outPath?) renders to an MP4 (or .mov if the background is transparent) and returns the file path.

First render downloads a headless Chrome (about 93 MB) one time.

CLI

Skip the MCP entirely if you want.

npm run render examples/list-reveal.json
# -> examples/list-reveal.mp4

npm run render path/to/spec.json /where/to/save.mp4

For live iteration on a spec with auto-reload as you edit the JSON:

npm run preview
# opens Remotion Studio at http://localhost:3000

Why this exists

Most short-form B2B video is a talking head with overlay graphics. A title at the top. A list of three points on cue. An icon or two. Done well, the overlays carry as much of the message as the speaker.

The three paths today: hire an editor (₹500-2000 per reel, slow loop, dependency on a person), subscribe to a SaaS like Submagic ($20/month, fixed style, AI-generated quality varies), or learn After Effects (real time investment, not scriptable from your terminal).

This kit is the fourth path. A small library of components keeps the visual language consistent across every reel. The agent writes the scene spec, the renderer produces the MP4, everything runs locally.

Reference

Everything below is the full schema. Keep it open as a lookup when you author specs by hand.

Scene spec, top-level

Common track fields

Motion (enter and exit)

{ kind, durationFrames, ease }. Available kind values:

ease: linear, easeIn, easeOut, easeInOut. Default easeOut.

Position

All track position fields are { x, y } as 0..1 fractions of the canvas. The track's geometric center is placed at that point.

Palette

Tokens defined in src/scene/theme.ts. The light palette (default):

Dark palette inverts these. Per-scene override via palette: { accent: "#E74C3C", ... }.

Per-track field reference

Each track kind below lists the fields it accepts beyond the common fields above.

title-overlay

Position is fixed at the top of the frame. There is no position field.

list-reveal

flow

comparison

hub

Layout is automatic by count. 2 satellites sit top and bottom. 3 form a triangle pointing up. 4 sit at cardinal positions.

icon

text

lottie

backgroundImage

Layers stack as background color, then image, then tint, then tracks.

Constraints

• Duration is 4 to 6 seconds. Validated.
• Aspect is 9:16, 1080×1920. Default.
• Frame rate is 30 fps.
• Only Tabler icons and line-style Lottie are supported.
• Theme is the Wednesday Solutions palette. Editable in src/scene/theme.ts.

Output formats

Project structure

video-overlay-kit/
├── bin/mcp.mjs              # MCP launcher
├── mcp/server.ts            # MCP server: list_icons, validate_scene, render_scene
├── scripts/render.ts        # CLI entry (npm run render)
├── src/
│   ├── Root.tsx, index.ts   # Remotion entry
│   ├── scene/
│   │   ├── types.ts         # Zod schema for the whole spec
│   │   ├── theme.ts         # Palette and font family
│   │   └── Scene.tsx        # Top-level renderer
│   ├── components/          # One file per track kind
│   ├── motion/              # Enter and exit transforms
│   └── lib/render.ts        # Shared by CLI and MCP
└── examples/                # Sample specs with their rendered MP4s and GIFs

Extending

To add a new track kind (quote for example):

1. Add QuoteTrackSchema in src/scene/types.ts, include it in TrackSchema, export the type.
2. Build src/components/Quote.tsx. Use useCurrentFrame() from Remotion and trackStyle from ../motion/primitives. Read colors from usePalette() and the font from FONT_FAMILY in src/scene/theme.ts.
3. Register the case in src/scene/Scene.tsx.
4. Update the schema hint in mcp/server.ts so the agent knows the new kind exists.

The renderer and MCP tool handlers do not need changes. Copy Flow.tsx or Hub.tsx as a starting point for choreographed components.

Cost

Zero per render. Local CPU and disk only. Free for individual use and small teams. Check each dependency's license if you are shipping commercially.

Credits

• Remotion is the React-based video rendering engine.
• Tabler Icons is the icon library.
• LottieFiles is the Lottie animation marketplace.
• Model Context Protocol is the standard used to expose the kit to Claude Code.

Support the project

VideoOverlayKit is free and MIT-licensed. If the kit saves you time or render budget, the easiest way to give back is to sponsor the project on GitHub. Sponsorships fund new components, better defaults, and bug fixes that ship faster than I can do them in evenings.

Wednesday Solutions (wednesday.is) is the studio behind the design system. If you want a custom build, a theme that matches your brand, or production help shipping AI features for a regulated industry, that's the way to reach the team.

License

MIT.

Issues, contributions

File issues at github.com/alichherawalla/video-overlay-kit. The schema in src/scene/types.ts is the contract. Propose the spec shape first when adding a new track kind, then the component.