# video-to-claude

Drop a screen recording, scrub the timeline, draw annotations on frames, click Send — the annotated WebPs land directly in your Claude Code conversation as vision input.

<table>
<tr>
<td><img src="https://raw.githubusercontent.com/adityaO5/video-to-claude/main/docs/screenshots/01-vtc-command.png" alt="Typing /vtc in Claude Code" width="320"/></td>
<td><img src="https://raw.githubusercontent.com/adityaO5/video-to-claude/main/docs/screenshots/06-send-back-in-claude.png" alt="Claude receives annotated frames" width="320"/></td>
<td><img src="https://raw.githubusercontent.com/adityaO5/video-to-claude/main/docs/screenshots/07-claude-describes.png" alt="Claude describes the annotated frame" width="320"/></td>
</tr>
<tr>
<td align="center"><em>Type <code>/vtc</code> in Claude Code</em></td>
<td align="center"><em>Claude receives your annotated frames</em></td>
<td align="center"><em>Claude reads the annotation and responds</em></td>
</tr>
</table>

---

## How it works

**1. Type `/vtc` in Claude Code**

The MCP server starts the dev server if it isn't running, creates a session, and opens `http://localhost:3000/capture/{id}` in your browser.

![/vtc command firing MCP tools](https://raw.githubusercontent.com/adityaO5/video-to-claude/main/docs/screenshots/01-vtc-command.png)

**2. Drop your video**

Drag a `.mp4`, `.mov`, `.webm`, or any common video file onto the upload zone. The file is probed with ffmpeg and the player becomes active.

![Upload drop zone](https://raw.githubusercontent.com/adityaO5/video-to-claude/main/docs/screenshots/02-upload.png)

**3. Scrub the timeline**

Use the scrubber or arrow keys to seek to the moment you want to capture. The canvas overlay sits on top of the video frame.

![Timeline scrubber](https://raw.githubusercontent.com/adityaO5/video-to-claude/main/docs/screenshots/03-timeline-scrub.png)

**4. Annotate the frame**

Draw arrows, boxes, freehand marks, and add text labels in red directly on the canvas. These annotations are baked into the exported WebP — Claude sees exactly what you circled.

![Canvas annotation](https://raw.githubusercontent.com/adityaO5/video-to-claude/main/docs/screenshots/04-annotate.png)

**5. Capture + repeat**

Click **Capture** to freeze the annotated frame. Repeat steps 3–4 for as many frames as you need. The capture strip at the bottom shows thumbnails.

![Capture strip](https://raw.githubusercontent.com/adityaO5/video-to-claude/main/docs/screenshots/05-capture-strip.png)

**6. Send**

Click **Send**. The MCP `await_capture` tool returns, delivering all annotated frames as image content blocks into the Claude Code conversation.

![Claude receives the WebPs](https://raw.githubusercontent.com/adityaO5/video-to-claude/main/docs/screenshots/06-send-back-in-claude.png)

**7. Claude describes what it sees**

Claude reads the annotation — the red arrow, the circled element, or the text label — and responds directly to what you marked. No re-explaining needed.

![Claude describes the annotated frame](https://raw.githubusercontent.com/adityaO5/video-to-claude/main/docs/screenshots/07-claude-describes.png)

---

## Prerequisites

- **Node.js 20+** (Node 24 recommended)
- **Claude Code CLI** installed ([install guide](https://claude.ai/download))
- Windows, macOS, or Linux
- No Python, no ffmpeg in PATH needed — both are bundled

---

## Install

### Option A — Claude Code plugin (recommended)

```bash
/plugin install github:adityaO5/video-to-claude
```

This installs the MCP server and `/video-to-claude:vtc` skill in one step. No separate MCP registration or command copying needed.

### Option B — npm (MCP only, no clone needed)

```bash
claude mcp add video-to-claude --scope user -- npx video-to-claude-mcp
```

Or manually add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "video-to-claude": {
      "command": "npx",
      "args": ["video-to-claude-mcp"]
    }
  }
}
```

Then add the `/vtc` command (see below).

### Option C — clone and build

```bash
git clone https://github.com/adityaO5/video-to-claude
cd video-to-claude
npm install
npm run mcp:build
```

Then register:

```bash
claude mcp add video-to-claude --scope user -- node /ABSOLUTE/PATH/TO/video-to-claude/dist/mcp/server.js
```

Replace `/ABSOLUTE/PATH/TO/video-to-claude` with the real path.  
**Windows example:** `C:/Users/you/repos/video-to-claude` (forward slashes work in JSON).

---

## Add the `/vtc` slash command (Options B and C only)

Plugin install (Option A) includes the skill automatically as `/video-to-claude:vtc`.

For Options B/C, the repo ships `.claude/commands/vtc.md`. Claude Code loads project-scoped slash commands only when your working directory is inside the cloned repo.

**To use `/vtc` from any directory**, copy the command file to your user-level commands folder:

```bash
# macOS / Linux
cp .claude/commands/vtc.md ~/.claude/commands/vtc.md

# Windows (PowerShell)
Copy-Item .claude\commands\vtc.md $HOME\.claude\commands\vtc.md
```

Restart Claude Code after any config change.

---

## Usage

```
/vtc
```

That's it. The browser opens, you upload + scrub + annotate + send, and the annotated frames appear in the conversation. Claude reads the red marks and acts on them.

---

## MCP tools

| Tool | Description |
|---|---|
| `start_capture_session` | Start dev server if needed, create session, open browser. Returns `sessionId`. |
| `await_capture` | Poll until user clicks Send (default 600 s timeout). Returns annotated WebPs as image content blocks. |

The `/vtc` slash command calls both in sequence automatically.

---

## Vision constraints

- Format: WebP (emitted by the tool)
- Target ≤ 2 MB per frame (hard cap 5 MB); quality retried down from 80 → 50 if needed
- Max width: 960 px
- Practical limit: ~20 frames before auto-downscale; soft cap ~100

---

## Troubleshooting

**Dev server didn't open?**  
Run `npm run dev` in the repo directory, then retry `/vtc`.

**MCP tools not visible in Claude Code?**  
Run `claude mcp list` to confirm registration. Restart Claude Code. If using the cloned repo, confirm `dist/mcp/server.js` exists (if not, re-run `npm run mcp:build`).

**Port conflict?**  
The MCP server scans ports 3000–3005 looking for the app. Run `npm run dev` on an open port or stop whatever else is using 3000.

**Upload stalls on large files?**  
The source is uploaded in 512 KB chunks. Very large files (> 2 GB) may take a moment on slow disks.

---

## Tech stack

- **Next.js 16** App Router (Node 24) — UI + REST API
- **ffmpeg-static** — video probing + single-frame extraction
- **sharp** — SVG annotation compositing + WebP encode with quality retry
- **@modelcontextprotocol/sdk** — MCP stdio transport

---

## License

MIT — see [LICENSE](LICENSE)