korovin-aa97/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)** — an
unedited session: a narrated recording goes in, a ready-to-file
bug-report.md comes out.
- **Silent recording → issue draft** —
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:
json
{
"mcpServers": {
"talkthrough": {
"command": "uvx",
"args": [
"--python",
">=3.11,
Cursor
~/.cursor/mcp.json (or project .cursor/mcp.json):
toml
[mcp_servers.talkthrough]
command = "uvx"
args = ["--python", ">=3.11,
Gemini CLI
~/.gemini/settings.json:
json
{
"mcpServers": {
"talkthrough": {
"command": "uvx",
"args": [
"--python",
">=3.11,
OpenClaw
~/.openclaw/openclaw.json:
json
{
"mcp": {
"talkthrough": {
"type": "local",
"command": [
"uvx",
"--python",
">=3.11,
Goose
~/.config/goose/config.yaml:
json
{
"mcpServers": {
"talkthrough": {
"command": "uvx",
"args": [
"--python",
">=3.11,
Windsurf
~/.codeium/windsurf/mcp_config.json:
json
{
"context_servers": {
"talkthrough": {
"source": "custom",
"command": {
"path": "uvx",
"args": [
"--python",
">=3.11,
Any other MCP stdio client uses the same server command: uvx --python ">=3.11,
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.11, =3.11, =3.11, Process ~/Desktop/recording.mov and triage it — or just invoke the
> triage-recording server prompt.
Tools
| Tool | What it does |
|---|---|
| process_media(path, recorded_at?, vocabulary?, language?, model?, diarize?, num_speakers?, force?) | Ingest a video/audio file: local STT, keyframes, OCR, wall-clock, opt-in speaker labels. Returns a compact summary. Idempotent by content hash — re-calls are instant; diarize=true on a processed job adds speakers without re-transcribing. |
| process_url(url, recorded_at?, vocabulary?, language?, model?, diarize?, num_speakers?, refresh?, force?) | The one network tool: download one public video/audio URL once (a direct https:// media link, one YouTube video, or any public video page yt-dlp can read — with the [url] extra), keep the source inside the job, then run the same local pipeline. Same-URL re-calls serve the stored job without network unless refresh=true; force=true rebuilds from the kept source; the raw URL is never stored. |