From b72b6634c8b57300f4dfebd684eca60fc39125f4 Mon Sep 17 00:00:00 2001
From: Slava Yultyyev <yultyyev@gmail.com>
Date: Sat, 7 Nov 2026 11:46:11 -0800
Subject: [PATCH 1/3] feat(cli): add clip doctor and an MCP doctor tool

Checks Node, which FFmpeg resolves and whether it has drawtext and
vidstab, a writable workspace, a caption font, and the optional
whisper.cpp binary and model. Each warning or failure carries its fix;
--json prints the report as JSON and the CLI exits 1 when a required
check fails. The MCP server exposes the same report as the doctor tool.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/cli.ts               |  15 ++
 src/ffmpeg/run.ts        |  28 +++-
 src/index.ts             |  20 ++-
 src/mcp/server.ts        |  11 ++
 src/tools/doctor.ts      | 352 +++++++++++++++++++++++++++++++++++++++
 tests/doctor.test.ts     | 301 +++++++++++++++++++++++++++++++++
 tests/mcp-server.test.ts |  23 +++
 7 files changed, 745 insertions(+), 5 deletions(-)
 create mode 100644 src/tools/doctor.ts
 create mode 100644 tests/doctor.test.ts

diff --git a/src/cli.ts b/src/cli.ts
index a773069..b704b91 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -9,6 +9,7 @@ import { adjust } from './tools/adjust.js';
 import { chromaKey } from './tools/chroma-key.js';
 import { concat } from './tools/concat.js';
 import { deleteOp } from './tools/delete-op.js';
+import { doctor, formatDoctorReport } from './tools/doctor.js';
 import { highlightReel } from './tools/highlight-reel.js';
 import { ingest } from './tools/ingest.js';
 import { inspect } from './tools/inspect.js';
@@ -74,6 +75,11 @@ MCP (drive the editor from Claude Desktop / any MCP client — no API key):
                                     client's MCP config; it exposes the timeline tools
                                     (show / edit / undo / redo / export).
 
+Setup:
+  clip doctor [--json]              Check Node, FFmpeg and its filters, the workspace, the
+                                    caption font and the optional whisper.cpp; print a fix
+                                    for each problem. Exits 1 when the editor can't run.
+
 Session safety (these tools do not log themselves):
   clip snapshot [<label>]           Save the current session as a named snapshot.
   clip undo [<snapshotLabel>]       Pop the last op, or restore a named snapshot.
@@ -558,6 +564,15 @@ async function main(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === 'doctor') {
+    const result = await doctor();
+    process.stdout.write(
+      args.includes('--json') ? `${JSON.stringify(result, null, 2)}\n` : formatDoctorReport(result),
+    );
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
   // ─── UI ──────────────────────────────────────────────────────────────
 
   if (command === 'ui') {
diff --git a/src/ffmpeg/run.ts b/src/ffmpeg/run.ts
index 6e4868b..57d8545 100644
--- a/src/ffmpeg/run.ts
+++ b/src/ffmpeg/run.ts
@@ -1,10 +1,30 @@
 import { execa } from 'execa';
 import ffmpegStatic from 'ffmpeg-static';
 
-// Resolution order: explicit override → bundled binary → system PATH.
-// The override exists so legally-cautious users can point at an LGPL-only
-// or system-managed FFmpeg; see the License section in the README.
-const ffmpegPath = process.env.MAKEMYCLIP_FFMPEG_PATH ?? ffmpegStatic ?? 'ffmpeg';
+export const FFMPEG_PATH_ENV = 'MAKEMYCLIP_FFMPEG_PATH';
+
+export interface FfmpegResolution {
+  path: string;
+  /** `env`: MAKEMYCLIP_FFMPEG_PATH; `bundled`: ffmpeg-static; `system`: `ffmpeg` on PATH. */
+  source: 'env' | 'bundled' | 'system';
+}
+
+/**
+ * Resolution order: explicit override → bundled binary → system PATH. The
+ * override exists so legally-cautious users can point at an LGPL-only or
+ * system-managed FFmpeg; see the License section in the README.
+ */
+export function resolveFfmpeg(
+  env: Record<string, string | undefined> = process.env,
+  bundled: string | null = ffmpegStatic,
+): FfmpegResolution {
+  const override = env[FFMPEG_PATH_ENV];
+  if (override !== undefined) return { path: override, source: 'env' };
+  if (bundled !== null) return { path: bundled, source: 'bundled' };
+  return { path: 'ffmpeg', source: 'system' };
+}
+
+const ffmpegPath = resolveFfmpeg().path;
 
 export interface FfmpegResult {
   stdout: string;
diff --git a/src/index.ts b/src/index.ts
index ea73e7b..ffbb158 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -53,7 +53,13 @@ export {
   probe,
   type VideoStream,
 } from './ffmpeg/probe.js';
-export { MissingFilterError, runFfmpeg } from './ffmpeg/run.js';
+export {
+  FFMPEG_PATH_ENV,
+  type FfmpegResolution,
+  MissingFilterError,
+  resolveFfmpeg,
+  runFfmpeg,
+} from './ffmpeg/run.js';
 export {
   appendOp,
   atomicWriteFile,
@@ -272,6 +278,18 @@ export {
   type DeleteOpResult,
   deleteOp,
 } from './tools/delete-op.js';
+export {
+  type DoctorCheck,
+  type DoctorCheckId,
+  type DoctorDeps,
+  DoctorInput,
+  type DoctorInputType,
+  type DoctorResult,
+  type DoctorStatus,
+  defaultDoctorDeps,
+  doctor,
+  formatDoctorReport,
+} from './tools/doctor.js';
 export {
   HighlightReelInput,
   type HighlightReelInputType,
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index d079759..bd4af9f 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -30,6 +30,7 @@ import { reviewCuts } from '../timeline/review.js';
 import { runPlan } from '../timeline/run-plan.js';
 import { transcribeClip } from '../timeline/transcript.js';
 import { EditableVerbSchema } from '../timeline/verbs.js';
+import { doctor } from '../tools/doctor.js';
 import { WhisperLanguageSchema } from '../transcribe/whisper.js';
 import {
   type CompositionSummary,
@@ -294,6 +295,16 @@ export function buildMcpServer(): McpServer {
     },
   );
 
+  server.registerTool(
+    'doctor',
+    {
+      title: 'Check the setup',
+      description:
+        'Check that this computer has what the editor needs: Node, FFmpeg and its text and stabilization filters, a writable workspace and a caption font, plus the optional local whisper.cpp and model for transcription. Each problem comes with its fix; settings named MAKEMYCLIP_* go in the env of this server in the MCP client config. Run it when the user asks whether their setup works, or when a tool fails with a setup error.',
+    },
+    async () => jsonResult(await doctor()),
+  );
+
   return server;
 }
 
diff --git a/src/tools/doctor.ts b/src/tools/doctor.ts
new file mode 100644
index 0000000..fba0493
--- /dev/null
+++ b/src/tools/doctor.ts
@@ -0,0 +1,352 @@
+import { randomBytes } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { mkdir, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { execa } from 'execa';
+import ffmpegStatic from 'ffmpeg-static';
+import { z } from 'zod';
+import { fontFileFor } from '../ffmpeg/font.js';
+import { FFMPEG_PATH_ENV, parseFilterList, resolveFfmpeg } from '../ffmpeg/run.js';
+import { WHISPER_MODEL_ENV, WHISPER_PATH_ENV } from '../transcribe/whisper.js';
+import { getWorkspace } from '../workspace.js';
+
+/**
+ * Check that this machine has what the editor needs, and say how to fix what
+ * it doesn't. Reads only local state: it runs the resolved FFmpeg and
+ * whisper.cpp, looks at files, and writes one temporary file in the workspace.
+ */
+
+export const DoctorInput = z.object({});
+
+export type DoctorInputType = z.infer<typeof DoctorInput>;
+
+/** `fail`: the editor can't run. `warn`: a feature is off. `skip`: not checked
+ *  because a check it depends on failed. */
+export type DoctorStatus = 'ok' | 'warn' | 'fail' | 'skip';
+
+export type DoctorCheckId =
+  | 'node'
+  | 'ffmpeg'
+  | 'drawtext'
+  | 'vidstab'
+  | 'workspace'
+  | 'font'
+  | 'whisper'
+  | 'whisper-model';
+
+export interface DoctorCheck {
+  id: DoctorCheckId;
+  label: string;
+  status: DoctorStatus;
+  /** What was found. */
+  detail: string;
+  /** What to do, for a `warn` or `fail`. */
+  fix?: string;
+}
+
+export interface DoctorResult {
+  /** False when any check failed. Warnings leave it true. */
+  ok: boolean;
+  checks: DoctorCheck[];
+}
+
+/** What the checks read from the machine; tests pass stubs. */
+export interface DoctorDeps {
+  env: Record<string, string | undefined>;
+  platform: NodeJS.Platform;
+  /** `process.versions.node`, e.g. "24.1.0". */
+  nodeVersion: string;
+  /** ffmpeg-static's binary path; null on a platform it has no build for. */
+  bundledFfmpeg: string | null;
+  workspace: string;
+  /** Run a binary to completion. Rejects like execa: `code` 'ENOENT' when it
+   *  isn't found, `exitCode` set when it ran and exited non-zero. */
+  run(file: string, args: string[]): Promise<{ stdout: string }>;
+  isFile(path: string): boolean;
+  /** Create the folder if needed, then write and remove a file in it. */
+  probeWritable(dir: string): Promise<void>;
+  /** The font file captions draw Latin text with; undefined means FFmpeg's default. */
+  captionFont(): string | undefined;
+}
+
+/** package.json `engines.node`. */
+const MIN_NODE_MAJOR = 24;
+const WORKSPACE_ENV = 'MAKEMYCLIP_WORKSPACE';
+const FALLBACK_FONT_ENV = 'MAKEMYCLIP_FALLBACK_FONT';
+
+export function defaultDoctorDeps(): DoctorDeps {
+  return {
+    env: process.env,
+    platform: process.platform,
+    nodeVersion: process.versions.node,
+    bundledFfmpeg: ffmpegStatic,
+    workspace: getWorkspace(),
+    run: async (file, args) => {
+      const { stdout } = await execa(file, args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 15_000,
+      });
+      return { stdout };
+    },
+    isFile: (path) => {
+      try {
+        return statSync(path).isFile();
+      } catch {
+        return false;
+      }
+    },
+    probeWritable: async (dir) => {
+      await mkdir(dir, { recursive: true });
+      const probe = join(dir, `.doctor-${randomBytes(4).toString('hex')}`);
+      await writeFile(probe, '');
+      await unlink(probe);
+    },
+    captionFont: () => fontFileFor('Aa', { always: true }),
+  };
+}
+
+export async function doctor(
+  _input: DoctorInputType = {},
+  deps: DoctorDeps = defaultDoctorDeps(),
+): Promise<DoctorResult> {
+  const { check: ffmpeg, filters } = await checkFfmpeg(deps);
+  const checks = [
+    checkNode(deps.nodeVersion),
+    ffmpeg,
+    checkDrawtext(filters),
+    checkVidstab(filters),
+    await checkWorkspace(deps),
+    checkFont(deps),
+    await checkWhisper(deps),
+    checkWhisperModel(deps),
+  ];
+  return { ok: checks.every((c) => c.status !== 'fail'), checks };
+}
+
+function checkNode(version: string): DoctorCheck {
+  const major = Number(version.split('.')[0]);
+  const base = { id: 'node', label: 'Node.js' } as const;
+  if (major >= MIN_NODE_MAJOR) return { ...base, status: 'ok', detail: version };
+  return {
+    ...base,
+    status: 'fail',
+    detail: `${version} is too old; the editor needs Node ${MIN_NODE_MAJOR} or newer.`,
+    fix: `Install Node ${MIN_NODE_MAJOR}+ from https://nodejs.org or with a version manager (nvm, fnm), then run this again.`,
+  };
+}
+
+const SOURCE_NAMES = {
+  env: FFMPEG_PATH_ENV,
+  bundled: 'bundled ffmpeg-static',
+  system: 'ffmpeg on PATH',
+} as const;
+
+function installFfmpegHint(platform: NodeJS.Platform): string {
+  if (platform === 'darwin') return '`brew install ffmpeg`';
+  if (platform === 'win32') return '`winget install Gyan.FFmpeg`';
+  return 'on Debian or Ubuntu, `sudo apt install ffmpeg`';
+}
+
+async function checkFfmpeg(
+  deps: DoctorDeps,
+): Promise<{ check: DoctorCheck; filters: Set<string> | null }> {
+  const { path, source } = resolveFfmpeg(deps.env, deps.bundledFfmpeg);
+  const base = { id: 'ffmpeg', label: 'FFmpeg' } as const;
+  try {
+    const { stdout } = await deps.run(path, ['-hide_banner', '-version']);
+    const version = /^ffmpeg version (\S+)/m.exec(stdout)?.[1] ?? 'unknown version';
+    const filters = parseFilterList((await deps.run(path, ['-hide_banner', '-filters'])).stdout);
+    return {
+      check: { ...base, status: 'ok', detail: `${version} (${SOURCE_NAMES[source]}) ${path}` },
+      filters,
+    };
+  } catch (err) {
+    const install = installFfmpegHint(deps.platform);
+    let fix: string;
+    if (source === 'env') {
+      fix = `Point ${FFMPEG_PATH_ENV} at a working ffmpeg binary, or unset it to use the bundled one.`;
+    } else if (source === 'bundled' && !deps.isFile(path)) {
+      fix =
+        'The bundled FFmpeg was never downloaded: ffmpeg-static fetches it in an install script, ' +
+        "which was skipped (npm's --ignore-scripts, or a package manager that blocks build scripts). " +
+        `Reinstall with install scripts allowed, or install FFmpeg (${install}) and set ${FFMPEG_PATH_ENV} to its path.`;
+    } else if (source === 'bundled') {
+      fix = `Install FFmpeg (${install}) and set ${FFMPEG_PATH_ENV} to its path.`;
+    } else {
+      fix = `ffmpeg-static has no build for this platform. Install FFmpeg (${install}) so \`ffmpeg\` is on PATH, or set ${FFMPEG_PATH_ENV} to its path.`;
+    }
+    return {
+      check: {
+        ...base,
+        status: 'fail',
+        detail: `${path} (${SOURCE_NAMES[source]}) doesn't run: ${reason(err)}.`,
+        fix,
+      },
+      filters: null,
+    };
+  }
+}
+
+const SKIPPED = 'Not checked: FFmpeg did not run.';
+
+function checkDrawtext(filters: Set<string> | null): DoctorCheck {
+  const base = { id: 'drawtext', label: 'Text and captions' } as const;
+  if (!filters) return { ...base, status: 'skip', detail: SKIPPED };
+  if (filters.has('drawtext')) return { ...base, status: 'ok', detail: 'drawtext filter' };
+  return {
+    ...base,
+    status: 'warn',
+    detail:
+      'This FFmpeg has no drawtext filter (it needs libfreetype and libharfbuzz), so text, title cards and captions cannot render.',
+    fix:
+      `Set ${FFMPEG_PATH_ENV} to an FFmpeg that lists drawtext in \`ffmpeg -hide_banner -filters\`. ` +
+      `On Debian or Ubuntu: \`sudo apt install ffmpeg\`, then \`export ${FFMPEG_PATH_ENV}=/usr/bin/ffmpeg\`.`,
+  };
+}
+
+function checkVidstab(filters: Set<string> | null): DoctorCheck {
+  const base = { id: 'vidstab', label: 'Stabilization' } as const;
+  if (!filters) return { ...base, status: 'skip', detail: SKIPPED };
+  if (filters.has('vidstabdetect') && filters.has('vidstabtransform')) {
+    return { ...base, status: 'ok', detail: 'vidstab filters' };
+  }
+  return {
+    ...base,
+    status: 'warn',
+    detail: 'This FFmpeg has no vidstab filters (libvidstab), so `clip stabilize` cannot run.',
+    fix: `Set ${FFMPEG_PATH_ENV} to an FFmpeg built with libvidstab (it lists vidstabdetect in \`ffmpeg -hide_banner -filters\`).`,
+  };
+}
+
+async function checkWorkspace(deps: DoctorDeps): Promise<DoctorCheck> {
+  const base = { id: 'workspace', label: 'Workspace' } as const;
+  const where = deps.env[WORKSPACE_ENV] === undefined ? 'default' : WORKSPACE_ENV;
+  try {
+    await deps.probeWritable(deps.workspace);
+    return { ...base, status: 'ok', detail: `${deps.workspace} (${where})` };
+  } catch (err) {
+    return {
+      ...base,
+      status: 'fail',
+      detail: `Cannot write to ${deps.workspace} (${where}): ${reason(err)}.`,
+      fix: `Set ${WORKSPACE_ENV} to a folder you can write to; the editor keeps its timeline, imports and exports there.`,
+    };
+  }
+}
+
+function checkFont(deps: DoctorDeps): DoctorCheck {
+  const base = { id: 'font', label: 'Caption font' } as const;
+  const font = deps.captionFont();
+  const explicit = deps.env[FALLBACK_FONT_ENV];
+  if (explicit && font !== explicit) {
+    return {
+      ...base,
+      status: 'warn',
+      detail: `${FALLBACK_FONT_ENV} (${explicit}) is missing, unreadable or has no Latin letters; captions use ${font ?? "FFmpeg's default font"}.`,
+      fix: `Point ${FALLBACK_FONT_ENV} at a .ttf, .otf or .ttc file, or unset it.`,
+    };
+  }
+  if (font) return { ...base, status: 'ok', detail: font };
+  const setFont = `${FALLBACK_FONT_ENV} to a .ttf, .otf or .ttc file`;
+  return {
+    ...base,
+    status: 'warn',
+    detail:
+      'No known font file found, so captions ask FFmpeg for its default font: slow per caption, and it fails on builds without fontconfig.',
+    fix:
+      deps.platform === 'linux'
+        ? `On Debian or Ubuntu, \`sudo apt install fonts-dejavu-core\`, or set ${setFont}.`
+        : `Set ${setFont}.`,
+  };
+}
+
+const WHISPER_PURPOSE = 'Optional: transcript cuts, retake removal and captions need it.';
+
+async function checkWhisper(deps: DoctorDeps): Promise<DoctorCheck> {
+  const base = { id: 'whisper', label: 'whisper.cpp (optional)' } as const;
+  const explicit = deps.env[WHISPER_PATH_ENV];
+  const binary = explicit ?? 'whisper-cli';
+  const where = explicit === undefined ? 'on PATH' : WHISPER_PATH_ENV;
+  try {
+    await deps.run(binary, ['--help']);
+  } catch (err) {
+    // It started and exited non-zero: some builds do that for --help.
+    const ran = typeof (err as { exitCode?: unknown }).exitCode === 'number';
+    if (!ran) {
+      const install =
+        deps.platform === 'darwin'
+          ? '`brew install whisper-cpp`'
+          : 'build it from https://github.com/ggml-org/whisper.cpp';
+      return {
+        ...base,
+        status: 'warn',
+        detail: `${binary} (${where}) doesn't run: ${reason(err)}. ${WHISPER_PURPOSE}`,
+        fix:
+          explicit === undefined
+            ? `Install whisper.cpp (${install}). If whisper-cli isn't on PATH, set ${WHISPER_PATH_ENV} to it.`
+            : `Point ${WHISPER_PATH_ENV} at the whisper-cli binary, or unset it to use whisper-cli on PATH.`,
+      };
+    }
+  }
+  return { ...base, status: 'ok', detail: `${binary} (${where})` };
+}
+
+function checkWhisperModel(deps: DoctorDeps): DoctorCheck {
+  const base = { id: 'whisper-model', label: 'Whisper model (optional)' } as const;
+  const model = deps.env[WHISPER_MODEL_ENV];
+  const fix = `Download a model such as ggml-base.en.bin from https://huggingface.co/ggerganov/whisper.cpp and set ${WHISPER_MODEL_ENV} to its path.`;
+  if (model === undefined || model === '') {
+    return {
+      ...base,
+      status: 'warn',
+      detail: `${WHISPER_MODEL_ENV} is not set. ${WHISPER_PURPOSE}`,
+      fix,
+    };
+  }
+  if (!deps.isFile(model)) {
+    return {
+      ...base,
+      status: 'warn',
+      detail: `${WHISPER_MODEL_ENV} points at ${model}, which is not a file.`,
+      fix,
+    };
+  }
+  return { ...base, status: 'ok', detail: model };
+}
+
+function reason(err: unknown): string {
+  const e = (err ?? {}) as { code?: unknown; shortMessage?: unknown; message?: unknown };
+  if (e.code === 'ENOENT') return 'not found';
+  if (e.code === 'EACCES') return 'permission denied';
+  const text = typeof e.shortMessage === 'string' ? e.shortMessage : (e.message ?? String(err));
+  return String(text).split('\n')[0] ?? '';
+}
+
+const MARKS: Record<DoctorStatus, string> = { ok: '✓', warn: '!', fail: '✗', skip: '-' };
+
+/** The report as terminal text: one line per check, a fix under each problem. */
+export function formatDoctorReport(result: DoctorResult): string {
+  const width = Math.max(...result.checks.map((c) => c.label.length));
+  const lines = ['MakeMyClip Editor setup', ''];
+  for (const c of result.checks) {
+    lines.push(`  ${MARKS[c.status]} ${c.label.padEnd(width)}  ${c.detail}`);
+    if (c.fix) lines.push(`    ${' '.repeat(width)}  Fix: ${c.fix}`);
+  }
+  const fails = result.checks.filter((c) => c.status === 'fail').length;
+  const warns = result.checks.filter((c) => c.status === 'warn').length;
+  lines.push('');
+  if (fails > 0) lines.push(`Not ready: ${plural(fails, 'problem')} to fix.`);
+  else if (warns > 0)
+    lines.push(`Ready. ${plural(warns, 'warning')}: those features stay off until fixed.`);
+  else lines.push('Ready. Everything is set up.');
+  if (fails + warns > 0) {
+    lines.push(
+      'Set environment variables in your shell profile; for `clip mcp`, set them in the MCP client config for the server.',
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function plural(n: number, word: string): string {
+  return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
diff --git a/tests/doctor.test.ts b/tests/doctor.test.ts
new file mode 100644
index 0000000..782a505
--- /dev/null
+++ b/tests/doctor.test.ts
@@ -0,0 +1,301 @@
+import { describe, expect, it } from 'vitest';
+import { resolveFfmpeg } from '../src/ffmpeg/run.js';
+import {
+  type DoctorCheck,
+  type DoctorCheckId,
+  type DoctorDeps,
+  doctor,
+  formatDoctorReport,
+} from '../src/tools/doctor.js';
+
+const BUNDLED = '/pkg/node_modules/ffmpeg-static/ffmpeg';
+const FILTERS = [
+  'Filters:',
+  ' T.C drawtext          V->V       Draw text on top of video frames using libfreetype library.',
+  ' ... vidstabdetect     V->V       Extract relative transformations, pass 1 of 2.',
+  ' ... vidstabtransform  V->V       Transform the frames, pass 2 of 2.',
+  ' TSC scale             V->V       Scale the input video size.',
+  '',
+].join('\n');
+
+function spawnError(code: string): Error {
+  return Object.assign(new Error(`spawn ${code}`), { code });
+}
+
+function exitError(exitCode: number): Error {
+  return Object.assign(new Error(`Command failed with exit code ${exitCode}`), { exitCode });
+}
+
+/** A machine where everything is set up; each test breaks one thing. */
+function deps(overrides: Partial<DoctorDeps> = {}): DoctorDeps & { calls: string[][] } {
+  const calls: string[][] = [];
+  return {
+    calls,
+    env: { MAKEMYCLIP_WHISPER_MODEL: '/models/ggml-base.en.bin' },
+    platform: 'linux',
+    nodeVersion: '24.1.0',
+    bundledFfmpeg: BUNDLED,
+    workspace: '/ws',
+    run: async (file, args) => {
+      calls.push([file, ...args]);
+      if (args.includes('-version')) return { stdout: 'ffmpeg version 7.1.1 Copyright (c)\n' };
+      if (args.includes('-filters')) return { stdout: FILTERS };
+      return { stdout: 'usage: whisper-cli [options] file0 file1 ...\n' };
+    },
+    isFile: () => true,
+    probeWritable: async () => undefined,
+    captionFont: () => '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf',
+    ...overrides,
+  };
+}
+
+function check(checks: DoctorCheck[], id: DoctorCheckId): DoctorCheck {
+  const found = checks.find((c) => c.id === id);
+  if (!found) throw new Error(`no ${id} check`);
+  return found;
+}
+
+describe('resolveFfmpeg', () => {
+  it('prefers the env override, then the bundled binary, then PATH', () => {
+    expect(resolveFfmpeg({ MAKEMYCLIP_FFMPEG_PATH: '/opt/ffmpeg' }, BUNDLED)).toEqual({
+      path: '/opt/ffmpeg',
+      source: 'env',
+    });
+    expect(resolveFfmpeg({}, BUNDLED)).toEqual({ path: BUNDLED, source: 'bundled' });
+    expect(resolveFfmpeg({}, null)).toEqual({ path: 'ffmpeg', source: 'system' });
+  });
+});
+
+describe('doctor', () => {
+  it('passes every check on a set-up machine, in a stable order', async () => {
+    const d = deps();
+    const result = await doctor({}, d);
+
+    expect(result.ok).toBe(true);
+    expect(result.checks.map((c) => [c.id, c.status])).toEqual([
+      ['node', 'ok'],
+      ['ffmpeg', 'ok'],
+      ['drawtext', 'ok'],
+      ['vidstab', 'ok'],
+      ['workspace', 'ok'],
+      ['font', 'ok'],
+      ['whisper', 'ok'],
+      ['whisper-model', 'ok'],
+    ]);
+    expect(result.checks.every((c) => c.fix === undefined)).toBe(true);
+    expect(check(result.checks, 'ffmpeg').detail).toBe(`7.1.1 (bundled ffmpeg-static) ${BUNDLED}`);
+    expect(check(result.checks, 'workspace').detail).toBe('/ws (default)');
+    expect(d.calls).toEqual([
+      [BUNDLED, '-hide_banner', '-version'],
+      [BUNDLED, '-hide_banner', '-filters'],
+      ['whisper-cli', '--help'],
+    ]);
+  });
+
+  it('fails on a Node older than the engines field', async () => {
+    const result = await doctor({}, deps({ nodeVersion: '22.11.0' }));
+
+    expect(result.ok).toBe(false);
+    expect(check(result.checks, 'node')).toMatchObject({
+      status: 'fail',
+      fix: expect.stringContaining('Node 24+'),
+    });
+  });
+
+  it('fails on a broken FFmpeg override and skips the filter checks', async () => {
+    const result = await doctor(
+      {},
+      deps({
+        env: { MAKEMYCLIP_FFMPEG_PATH: '/nope/ffmpeg' },
+        run: async () => {
+          throw spawnError('ENOENT');
+        },
+      }),
+    );
+
+    expect(result.ok).toBe(false);
+    expect(check(result.checks, 'ffmpeg')).toMatchObject({
+      status: 'fail',
+      detail: "/nope/ffmpeg (MAKEMYCLIP_FFMPEG_PATH) doesn't run: not found.",
+      fix: expect.stringContaining('unset it to use the bundled one'),
+    });
+    expect(check(result.checks, 'drawtext').status).toBe('skip');
+    expect(check(result.checks, 'vidstab').status).toBe('skip');
+  });
+
+  it('explains a bundled FFmpeg whose install script never ran', async () => {
+    const result = await doctor(
+      {},
+      deps({
+        isFile: (path) => path !== BUNDLED,
+        run: async () => {
+          throw spawnError('ENOENT');
+        },
+      }),
+    );
+
+    expect(check(result.checks, 'ffmpeg')).toMatchObject({
+      status: 'fail',
+      fix: expect.stringMatching(/install script.*sudo apt install ffmpeg.*MAKEMYCLIP_FFMPEG_PATH/),
+    });
+  });
+
+  it('points a platform with no bundled build at a system FFmpeg', async () => {
+    const result = await doctor(
+      {},
+      deps({
+        platform: 'darwin',
+        bundledFfmpeg: null,
+        run: async () => {
+          throw spawnError('ENOENT');
+        },
+      }),
+    );
+
+    expect(check(result.checks, 'ffmpeg')).toMatchObject({
+      status: 'fail',
+      detail: "ffmpeg (ffmpeg on PATH) doesn't run: not found.",
+      fix: expect.stringContaining('`brew install ffmpeg`'),
+    });
+  });
+
+  it('warns, without failing, when FFmpeg lacks drawtext or vidstab', async () => {
+    const result = await doctor(
+      {},
+      deps({
+        run: async (_file, args) => ({
+          stdout: args.includes('-version')
+            ? 'ffmpeg version 6.1 Copyright\n'
+            : ' TSC scale             V->V       Scale the input video size.\n',
+        }),
+      }),
+    );
+
+    expect(result.ok).toBe(true);
+    expect(check(result.checks, 'drawtext')).toMatchObject({
+      status: 'warn',
+      fix: expect.stringContaining('MAKEMYCLIP_FFMPEG_PATH=/usr/bin/ffmpeg'),
+    });
+    expect(check(result.checks, 'vidstab')).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('clip stabilize'),
+    });
+  });
+
+  it('fails when the workspace is not writable', async () => {
+    const result = await doctor(
+      {},
+      deps({
+        env: { MAKEMYCLIP_WORKSPACE: '/ro', MAKEMYCLIP_WHISPER_MODEL: '/m.bin' },
+        workspace: '/ro',
+        probeWritable: async () => {
+          throw Object.assign(new Error("EACCES: permission denied, mkdir '/ro'"), {
+            code: 'EACCES',
+          });
+        },
+      }),
+    );
+
+    expect(result.ok).toBe(false);
+    expect(check(result.checks, 'workspace')).toMatchObject({
+      status: 'fail',
+      detail: 'Cannot write to /ro (MAKEMYCLIP_WORKSPACE): permission denied.',
+      fix: expect.stringContaining('MAKEMYCLIP_WORKSPACE'),
+    });
+  });
+
+  it('warns when no caption font is found', async () => {
+    const result = await doctor({}, deps({ captionFont: () => undefined }));
+
+    expect(check(result.checks, 'font')).toMatchObject({
+      status: 'warn',
+      fix: expect.stringMatching(/fonts-dejavu-core.*MAKEMYCLIP_FALLBACK_FONT/),
+    });
+  });
+
+  it('warns when MAKEMYCLIP_FALLBACK_FONT is set but not used', async () => {
+    const result = await doctor(
+      {},
+      deps({
+        env: { MAKEMYCLIP_FALLBACK_FONT: '/fonts/missing.ttf', MAKEMYCLIP_WHISPER_MODEL: '/m.bin' },
+      }),
+    );
+
+    expect(check(result.checks, 'font')).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('/fonts/missing.ttf'),
+    });
+  });
+
+  it('warns about a missing whisper.cpp with the platform install', async () => {
+    const result = await doctor(
+      {},
+      deps({
+        platform: 'darwin',
+        run: async (file, args) => {
+          if (file === 'whisper-cli') throw spawnError('ENOENT');
+          return deps().run(file, args);
+        },
+      }),
+    );
+
+    expect(result.ok).toBe(true);
+    expect(check(result.checks, 'whisper')).toMatchObject({
+      status: 'warn',
+      fix: expect.stringContaining('`brew install whisper-cpp`'),
+    });
+  });
+
+  it('accepts a whisper.cpp that exits non-zero for --help', async () => {
+    const result = await doctor(
+      {},
+      deps({
+        env: { MAKEMYCLIP_WHISPER_PATH: '/bin/whisper', MAKEMYCLIP_WHISPER_MODEL: '/m.bin' },
+        run: async (file, args) => {
+          if (file === '/bin/whisper') throw exitError(1);
+          return deps().run(file, args);
+        },
+      }),
+    );
+
+    expect(check(result.checks, 'whisper')).toMatchObject({
+      status: 'ok',
+      detail: '/bin/whisper (MAKEMYCLIP_WHISPER_PATH)',
+    });
+  });
+
+  it('warns when the whisper model is unset or missing', async () => {
+    const unset = await doctor({}, deps({ env: {} }));
+    const missing = await doctor(
+      {},
+      deps({ isFile: (path) => path !== '/models/ggml-base.en.bin' }),
+    );
+
+    expect(check(unset.checks, 'whisper-model')).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('MAKEMYCLIP_WHISPER_MODEL is not set'),
+      fix: expect.stringContaining('ggml-base.en.bin'),
+    });
+    expect(check(missing.checks, 'whisper-model')).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('not a file'),
+    });
+  });
+});
+
+describe('formatDoctorReport', () => {
+  it('prints one line per check, a fix under each problem, and a verdict', async () => {
+    const ready = formatDoctorReport(await doctor({}, deps()));
+    const warned = formatDoctorReport(await doctor({}, deps({ env: {} })));
+    const broken = formatDoctorReport(await doctor({}, deps({ nodeVersion: '20.0.0' })));
+
+    expect(ready).toContain('✓ FFmpeg');
+    expect(ready).toContain('Ready. Everything is set up.');
+    expect(ready).not.toContain('Fix:');
+    expect(warned).toContain('! Whisper model (optional)');
+    expect(warned).toContain('Fix: Download a model');
+    expect(warned).toContain('Ready. 1 warning: those features stay off until fixed.');
+    expect(broken).toContain('✗ Node.js');
+    expect(broken).toContain('Not ready: 1 problem to fix.');
+  });
+});
diff --git a/tests/mcp-server.test.ts b/tests/mcp-server.test.ts
index de0f332..3cf2207 100644
--- a/tests/mcp-server.test.ts
+++ b/tests/mcp-server.test.ts
@@ -52,6 +52,7 @@ describe('MCP server', () => {
     try {
       const { tools } = await client.listTools();
       expect(tools.map((t) => t.name).sort()).toEqual([
+        'doctor',
         'timeline_check',
         'timeline_edit',
         'timeline_export',
@@ -65,6 +66,28 @@ describe('MCP server', () => {
     }
   });
 
+  it('answers "is my setup OK?" with the doctor checks', async () => {
+    const { client, close } = await connect();
+    try {
+      const report = payload(await client.callTool({ name: 'doctor', arguments: {} }));
+      const checks = report.checks as { id: string; status: string }[];
+      expect(typeof report.ok).toBe('boolean');
+      expect(checks.map((c) => c.id)).toEqual([
+        'node',
+        'ffmpeg',
+        'drawtext',
+        'vidstab',
+        'workspace',
+        'font',
+        'whisper',
+        'whisper-model',
+      ]);
+      expect(checks.find((c) => c.id === 'workspace')?.status).toBe('ok');
+    } finally {
+      await close();
+    }
+  });
+
   it('advertises its package version in the handshake', async () => {
     const { client, close } = await connect();
     try {

From 72527173bbf172117a3d409f02d54b026fa1bd1d Mon Sep 17 00:00:00 2001
From: Slava Yultyyev <yultyyev@gmail.com>
Date: Sat, 7 Nov 2026 11:46:11 -0800
Subject: [PATCH 2/3] docs(docs): point setup help at clip doctor

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md |  2 +-
 README.md | 10 +++++++++-
 SKILL.md  |  2 +-
 llms.txt  |  1 +
 4 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b9df9ba..18b35f3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -97,7 +97,7 @@ Each tool lives in `src/tools/<name>.ts` and exports:
 Rules:
 - One tool per file.
 - Zod schema is the single source of input truth.
-- Handlers return a typed result — `{ path, ... }` for tools that write a file (`ingest.ts`, `inspect.ts`, `split.ts`, `undo.ts` and `delete-op.ts` return other shapes) — never raw FFmpeg output.
+- Handlers return a typed result — `{ path, ... }` for tools that write a file (`ingest.ts`, `inspect.ts`, `split.ts`, `undo.ts`, `delete-op.ts` and `doctor.ts` return other shapes) — never raw FFmpeg output.
 - Handlers must be idempotent given the same input + workspace state.
 
 ## FFmpeg
diff --git a/README.md b/README.md
index cd8153b..b067427 100644
--- a/README.md
+++ b/README.md
@@ -84,7 +84,7 @@ clip ui   # opens http://127.0.0.1:5573
 }
 ```
 
-The Claude Code skill auto-discovers triggers and shells out via `npx -y` on demand. The MCP server exposes the timeline tools (show / edit / check / transcribe / undo / redo / export) over stdio; media stays confined to `MAKEMYCLIP_WORKSPACE`, and `MAKEMYCLIP_WHISPER_MODEL` is only needed for transcription and captions. Everything runs locally and offline — no API key.
+The Claude Code skill auto-discovers triggers and shells out via `npx -y` on demand. The MCP server exposes the timeline tools (show / edit / check / transcribe / undo / redo / export) and a `doctor` setup check over stdio; media stays confined to `MAKEMYCLIP_WORKSPACE`, and `MAKEMYCLIP_WHISPER_MODEL` is only needed for transcription and captions. Everything runs locally and offline — no API key.
 
 **Optional: local transcription** (for editing by transcript, removing retakes, and captions):
 
@@ -95,6 +95,14 @@ export MAKEMYCLIP_WHISPER_MODEL=/path/to/ggml-base.en.bin
 
 Download a model such as `ggml-base.en.bin` from [huggingface.co/ggerganov/whisper.cpp](https://huggingface.co/ggerganov/whisper.cpp), and set `MAKEMYCLIP_WHISPER_PATH` if `whisper-cli` isn't on your `PATH`. The editor never downloads a model itself.
 
+**Check your setup:**
+
+```bash
+npx -y @makemyclip/editor doctor   # add --json for a machine-readable report
+```
+
+It checks Node, which FFmpeg runs and whether it can draw text and captions, the workspace, a caption font, and the optional whisper.cpp and model, and prints the fix for anything missing. In Claude Desktop or another MCP client, ask "is my setup OK?" and Claude runs the same check.
+
 ---
 
 ## Quick start: clean up a talking-head recording
diff --git a/SKILL.md b/SKILL.md
index 41c7b90..5a522fc 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -365,7 +365,7 @@ These are the recovery loop the council called must-haves. Snapshot before any u
 npx skills add MakeMyClip/editor
 ```
 
-That's it.
+That's it. If a command fails with a setup error (FFmpeg, its drawtext filter, whisper.cpp, a font, the workspace), or the user asks whether their setup works, run `npx -y @makemyclip/editor doctor`: it lists each check with the fix for anything missing.
 
 ## License
 
diff --git a/llms.txt b/llms.txt
index 1792b18..00ced9f 100644
--- a/llms.txt
+++ b/llms.txt
@@ -30,6 +30,7 @@
 - Browser UI: `clip ui` (opens http://127.0.0.1:5573)
 - MCP server: `npx -y @makemyclip/editor mcp` (stdio), with `MAKEMYCLIP_WORKSPACE` set to the media folder
 - Transcription (optional): install whisper.cpp (macOS: `brew install whisper-cpp`), download a model such as `ggml-base.en.bin`, set `MAKEMYCLIP_WHISPER_MODEL` to its path
+- Setup check: `npx -y @makemyclip/editor doctor` (or the MCP `doctor` tool) lists what's missing and how to fix it
 
 ## Tool catalog (19 tools)
 

From 6eb711dff1d2a67e36b4b1898ff077b76c727847 Mon Sep 17 00:00:00 2001
From: Slava Yultyyev <yultyyev@gmail.com>
Date: Sat, 7 Nov 2026 11:49:00 -0800
Subject: [PATCH 3/3] fix(cli): count a whisper-cli that dies on startup as
 broken in doctor

A non-zero exit passes only when whisper-cli printed its usage; a build
that can't load its libraries now warns with the loader's message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/tools/doctor.ts  | 28 +++++++++++++++++++++-------
 tests/doctor.test.ts | 34 +++++++++++++++++++++++++++++++---
 2 files changed, 52 insertions(+), 10 deletions(-)

diff --git a/src/tools/doctor.ts b/src/tools/doctor.ts
index fba0493..aef2312 100644
--- a/src/tools/doctor.ts
+++ b/src/tools/doctor.ts
@@ -60,7 +60,7 @@ export interface DoctorDeps {
   bundledFfmpeg: string | null;
   workspace: string;
   /** Run a binary to completion. Rejects like execa: `code` 'ENOENT' when it
-   *  isn't found, `exitCode` set when it ran and exited non-zero. */
+   *  isn't found; `exitCode`, `stdout` and `stderr` set when it exited non-zero. */
   run(file: string, args: string[]): Promise<{ stdout: string }>;
   isFile(path: string): boolean;
   /** Create the folder if needed, then write and remove a file in it. */
@@ -270,9 +270,9 @@ async function checkWhisper(deps: DoctorDeps): Promise<DoctorCheck> {
   try {
     await deps.run(binary, ['--help']);
   } catch (err) {
-    // It started and exited non-zero: some builds do that for --help.
-    const ran = typeof (err as { exitCode?: unknown }).exitCode === 'number';
-    if (!ran) {
+    // Some builds exit non-zero after printing help; one that can't load its
+    // libraries exits non-zero too, but prints no usage line.
+    if (!printedHelp(err)) {
       const install =
         deps.platform === 'darwin'
           ? '`brew install whisper-cpp`'
@@ -283,7 +283,7 @@ async function checkWhisper(deps: DoctorDeps): Promise<DoctorCheck> {
         detail: `${binary} (${where}) doesn't run: ${reason(err)}. ${WHISPER_PURPOSE}`,
         fix:
           explicit === undefined
-            ? `Install whisper.cpp (${install}). If whisper-cli isn't on PATH, set ${WHISPER_PATH_ENV} to it.`
+            ? `Install or reinstall whisper.cpp (${install}). If whisper-cli isn't on PATH, set ${WHISPER_PATH_ENV} to it.`
             : `Point ${WHISPER_PATH_ENV} at the whisper-cli binary, or unset it to use whisper-cli on PATH.`,
       };
     }
@@ -291,6 +291,11 @@ async function checkWhisper(deps: DoctorDeps): Promise<DoctorCheck> {
   return { ...base, status: 'ok', detail: `${binary} (${where})` };
 }
 
+function printedHelp(err: unknown): boolean {
+  const e = (err ?? {}) as { exitCode?: unknown; stdout?: unknown; stderr?: unknown };
+  return typeof e.exitCode === 'number' && /usage:/i.test(`${e.stdout ?? ''}\n${e.stderr ?? ''}`);
+}
+
 function checkWhisperModel(deps: DoctorDeps): DoctorCheck {
   const base = { id: 'whisper-model', label: 'Whisper model (optional)' } as const;
   const model = deps.env[WHISPER_MODEL_ENV];
@@ -315,11 +320,20 @@ function checkWhisperModel(deps: DoctorDeps): DoctorCheck {
 }
 
 function reason(err: unknown): string {
-  const e = (err ?? {}) as { code?: unknown; shortMessage?: unknown; message?: unknown };
+  const e = (err ?? {}) as {
+    code?: unknown;
+    shortMessage?: unknown;
+    message?: unknown;
+    stderr?: unknown;
+  };
   if (e.code === 'ENOENT') return 'not found';
   if (e.code === 'EACCES') return 'permission denied';
   const text = typeof e.shortMessage === 'string' ? e.shortMessage : (e.message ?? String(err));
-  return String(text).split('\n')[0] ?? '';
+  const firstLine = String(text).split('\n')[0] ?? '';
+  // A binary that starts and dies says why on stderr (a missing shared library).
+  const said =
+    typeof e.stderr === 'string' ? e.stderr.split('\n').find((l) => l.trim()) : undefined;
+  return said ? `${firstLine} (${said.trim()})` : firstLine;
 }
 
 const MARKS: Record<DoctorStatus, string> = { ok: '✓', warn: '!', fail: '✗', skip: '-' };
diff --git a/tests/doctor.test.ts b/tests/doctor.test.ts
index 782a505..62b7909 100644
--- a/tests/doctor.test.ts
+++ b/tests/doctor.test.ts
@@ -22,8 +22,13 @@ function spawnError(code: string): Error {
   return Object.assign(new Error(`spawn ${code}`), { code });
 }
 
-function exitError(exitCode: number): Error {
-  return Object.assign(new Error(`Command failed with exit code ${exitCode}`), { exitCode });
+function exitError(exitCode: number, stderr: string): Error {
+  return Object.assign(new Error(`Command failed with exit code ${exitCode}`), {
+    shortMessage: `Command failed with exit code ${exitCode}`,
+    exitCode,
+    stdout: '',
+    stderr,
+  });
 }
 
 /** A machine where everything is set up; each test breaks one thing. */
@@ -252,7 +257,7 @@ describe('doctor', () => {
       deps({
         env: { MAKEMYCLIP_WHISPER_PATH: '/bin/whisper', MAKEMYCLIP_WHISPER_MODEL: '/m.bin' },
         run: async (file, args) => {
-          if (file === '/bin/whisper') throw exitError(1);
+          if (file === '/bin/whisper') throw exitError(1, '\nusage: whisper-cli [options] file0\n');
           return deps().run(file, args);
         },
       }),
@@ -264,6 +269,29 @@ describe('doctor', () => {
     });
   });
 
+  it('warns about a whisper.cpp that exits without printing help', async () => {
+    const result = await doctor(
+      {},
+      deps({
+        run: async (file, args) => {
+          if (file === 'whisper-cli') {
+            throw exitError(
+              127,
+              'whisper-cli: error while loading shared libraries: libwhisper.so.1',
+            );
+          }
+          return deps().run(file, args);
+        },
+      }),
+    );
+
+    expect(check(result.checks, 'whisper')).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('libwhisper.so.1'),
+      fix: expect.stringContaining('reinstall whisper.cpp'),
+    });
+  });
+
   it('warns when the whisper model is unset or missing', async () => {
     const unset = await doctor({}, deps({ env: {} }));
     const missing = await doctor(