Talkthrough

talkthrough-mcp

Quickstart · Tools · Benchmarks · FAQ · Troubleshooting · Changelog · Contributing

Don't write a bug report. Record it.

Give Claude Code or Codex a narrated .mov/.mp4 — or a public video link — and talkthrough turns it into searchable transcript, exact frames, OCR and wall-clock timestamps, locally — so your agent writes an evidence-backed issue draft or investigates the fix.

Also works for meetings, workshops, product demos, and production incidents.

*Illustration — an animation of the /talkthrough:bug storyline, not a screen capture: the recording is indexed locally (transcript · keyframes · OCR · wall-clock), the evidence checkpoint is assembled, and the draft is ready to file with your own tracker tooling (gh, Jira, a GitHub MCP server — talkthrough itself never leaves your machine and never posts anything).*

Real runs, no animation:

• [▶ Watch the demo with sound (1:18)](https://youtu.be/nHfGfEiVdE8) — an unedited session: a narrated recording goes in, a ready-to-file bug-report.md comes out.
• [Silent recording → issue draft](examples/bug-from-silent-recording/) — the whole thing as files you can re-run: a Playwright-recorded, audio-free .mp4 and the unedited agent output. Every number is reproducible — processing that file gives job_id 8703a66bbe77a7d0 (the job id *is* the sha256 prefix, so shasum -a 256 predicts it), 17 keyframes / 4 unique, and 0 transcript segments because there is no audio track.

Quickstart

One command, no system dependencies: ffmpeg falls back to a bundled build, OCR is pip-only, and whisper models download themselves on first use. The only prerequisite is uv (brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh).

Cold setup has two separate stages: uvx first resolves a compatible Python and the pinned server environment, then the first process_media downloads any missing media/model assets. A plugin update can create a new environment and, without system ffmpeg, fetch the ~80 MB bundled ffmpeg again; shared Whisper/OCR/diarization caches and warm, network-free jobs remain reusable. See Troubleshooting.

Claude Code

Two install paths — pick one, not both (the plugin already includes the server; installing both would register it twice):

Server only — the 9 tools + 6 prompts, and nothing else on your system. Choose this for a minimal setup, or when you manage MCP servers yourself across several clients:

claude mcp add -s user talkthrough -- uvx --python ">=3.11,<3.14" "talkthrough-mcp[diarization,url]"

Full plugin — the same server, plus native slash commands (/talkthrough:bug, /talkthrough:triage-recording, …) that handle the ceremony for you, a ready-made triage subagent, and an agent skill that teaches Claude the workflow. Choose this for the best out-of-the-box experience:

/plugin marketplace add korovin-aa97/talkthrough-mcp

/plugin install talkthrough@talkthrough

Every other MCP client

Claude Desktop

claude_desktop_config.json:

{

"mcpServers": { "talkthrough": { "command": "uvx", "args": [ "--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]" ] } } }

More: integrations/claude-desktop/

Cursor

~/.cursor/mcp.json (or project .cursor/mcp.json):

{

"mcpServers": { "talkthrough": { "command": "uvx", "args": [ "--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]" ] } } }

More: integrations/cursor/

OpenAI Codex CLI

~/.codex/config.toml (or project-scoped .codex/config.toml in trusted projects):

[mcp_servers.talkthrough]

command = "uvx" args = ["--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]"]

More: integrations/codex/

Gemini CLI

~/.gemini/settings.json:

{

"mcpServers": { "talkthrough": { "command": "uvx", "args": [ "--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]" ] } } }

More: integrations/gemini-cli/

Cline / Roo Code

cline_mcp_settings.json (via MCP Servers UI):

{

"mcpServers": { "talkthrough": { "command": "uvx", "args": [ "--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]" ] } } }

More: integrations/cline/

OpenClaw

~/.openclaw/openclaw.json:

{

"mcp": { "servers": { "talkthrough": { "command": "uvx", "args": [ "--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]" ] } } } }

More: integrations/openclaw/

OpenCode

opencode.json (project) or ~/.config/opencode/opencode.json:

{

"mcp": { "talkthrough": { "type": "local", "command": [ "uvx", "--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]" ], "enabled": true } } }

More: integrations/opencode/

Goose

~/.config/goose/config.yaml:

extensions:

talkthrough: enabled: true type: stdio cmd: uvx args: ["--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]"]

More: integrations/goose/

GitHub Copilot CLI

~/.copilot/mcp-config.json:

{

"mcpServers": { "talkthrough": { "command": "uvx", "args": [ "--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]" ] } } }

More: integrations/copilot-cli/

Windsurf

~/.codeium/windsurf/mcp_config.json:

{

"mcpServers": { "talkthrough": { "command": "uvx", "args": [ "--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]" ] } } }

More: integrations/windsurf/

Zed

settings.json (Zed):

{

"context_servers": { "talkthrough": { "source": "custom", "command": { "path": "uvx", "args": [ "--python", ">=3.11,<3.14", "talkthrough-mcp[diarization,url]" ] } } } }

More: integrations/zed/

Any other MCP stdio client uses the same server command: uvx --python ">=3.11,<3.14" "talkthrough-mcp[diarization,url]". Per-engine folders with exactly these snippets plus verification steps live in integrations/; agents can self-install via llms-install.md.

Who said what (speaker diarization) — included in the configs above

Multi-person recordings (meetings, interviews, panels) can carry S1/S2/… speaker labels. Every install button, snippet, and the plugin above already ship the [diarization] engine, so asking your agent "who said what" just works — diarization itself still runs only when requested per call (process_media(path=..., diarize=true, num_speakers= )), and its models download once on first use.

Prefer the minimal server without the diarization engine? Use uvx --python ">=3.11,<3.14" talkthrough-mcp as the command instead (the MCP registry entry also resolves to this lean form) — an explicit diarize=true will then answer with the one-line install fix. Details in Speakers.

Updating to 0.4.4

Update your plugin or generated config, then warm its exact pinned launcher before reconnecting the MCP client:

uvx --python ">=3.11,<3.14" "talkthrough-mcp[diarization,url]==0.4.4" --version

The output should name 0.4.4 and both extras. This prepares dependencies; the first recording can still need model/tool downloads. A cold environment can exceed the client's startup timeout. See startup recovery. Existing jobs need no migration.

Upgrading from 0.3.x

Regenerated configs and the plugin carry [diarization,url]. A config you wrote by hand for 0.3.x — uvx --python ">=3.11,<3.14" talkthrough-mcp, or a pin without the url extra — upgrades the server in place and lists the new process_url tool, but only direct https:// media links work until the extra is there: YouTube and video pages answer with the one-line install fix. Add url to your command (uvx --python ">=3.11,<3.14" "talkthrough-mcp[diarization,url]"), restart the client, and check with talkthrough-mcp --version (0.4.1+), which names the extras the environment has; the server logs the same line to stderr at every start, so your client's MCP log shows it too.

Local checkout (development)

git clone https://github.com/korovin-aa97/talkthroug