Continuityguard

ContinuityGuard

Install • Quickstart • CLI reference • FAQ • Contributing

A local, zero-network CLI that scores your already-generated AI short-drama clips for character-consistency drift and physically implausible motion, before you spend render credits finding out the hard way.

npm install -g continuityguard-cli

AI short-drama generation is having a real moment, and every title is a stack of individually generated shots. Generation models still drift: a character's face shifts slightly between cuts, or a motion jumps in a way that reads as physically wrong the moment a human watches it. Catching that after render is expensive. ContinuityGuard scans a folder of already-generated clips or frames from any pipeline and flags the shots worth a second look before you commit to a re-render.

Install

Two independent, equally first-class distributions ship the same scoring logic and the same bundled MobileNetV2 ONNX model. Both are published and installable today: the Python package on PyPI, and the TypeScript/npm package on the npm registry.

Python:

pip install continuityguard-cli

See python/README.md for the Python-specific quickstart, CLI reference, and library API.

TypeScript/npm:

npm install -g continuityguard-cli

That puts the continuityguard command on your PATH -- run it with continuityguard scan . To build from source instead (for local development or to track main), clone the repo and run npm install && npm run build, then run the CLI with node dist/cli.js scan , or npm link it locally to get the continuityguard command from your working copy.

Features

• Two independent scoring passes in one scan. Character-consistency (cosine similarity between MobileNetV2 embeddings of same-named-character crops) and physics-plausibility (frame-to-frame motion-discontinuity heuristic against each shot's own local baseline) both run from a single scan command.
• Zero network calls, checked mechanically on every push. npm run verify:zero-network monkey-patches every network entry point Node exposes and runs a real scan against this repo's own fixtures in CI; it fails loudly if any code path ever tries to reach the network.
• Structured output for both humans and pipelines. The same scan writes a human-readable terminal summary and a full machine-readable JSON report (--json), so a QA reviewer and a CI script can consume the same result.
• Fast on ordinary hardware. The 8-clip fixture scan (decode, both scoring passes, and report write) completed in 0.53 to 0.63 seconds across repeated runs on a laptop CPU during this audit. No GPU required; scoring runs on CPU via onnxruntime-node and a 14MB bundled model.
• Every flag comes with a reason you can check yourself. Each flagged shot carries the clip name, the numeric score, the threshold it crossed, and a plain-language explanation, sourced directly from the JSON report's reason field.

What it does

Real output, from this repo's own committed synthetic fixtures (src/score/testdata/clips/, generated by src/score/testdata/generate-fixtures.sh; no real short-drama footage was available for this build, so every number below is reproducible, not illustrative):

$ node dist/cli.js scan src/score/testdata/clips

ContinuityGuard v0.1 -- Local Character-Consistency & Physics-QA Scoring

Scanning: src/score/testdata/clips (8 clips, ffmpeg decode)

[SCORED] CG01 Clip Ingestion 8 clips decoded, 51 frames extracted

[SCORED] CG02 Character-Consistency Scoring 3 named characters tracked across 8 clips 1 shot(s) flagged: low cross-shot similarity (below 0.88 cosine threshold) kenji_shot02.mp4 -- "kenji" similarity 0.77 vs. reference (kenji_shot01.mp4) NOTE: consistency scoring is best-validated on photorealistic content. Accuracy on stylized/anime-adjacent character designs is unverified -- treat flags on stylized content as a prompt for human review, not a confirmed defect. See "Known limitations" below.

[SCORED] CG03 Physics-Plausibility Heuristic 2 shot(s) flagged: frame-to-frame motion discontinuity above threshold action-discontinuity.mp4 @ frame 4-5 -- discontinuity 8.25x local baseline action-discontinuity.mp4 @ frame 5-6 -- discontinuity 8.32x local baseline This is a heuristic proxy, not a physics simulator. It flags shots for human review. It does not "detect" a physics violation.

Report written to ./continuityguard-report.json Human-readable summary above. Use --json for the full structured report. Scan time: 0.6s. Nothing left this machine. No network calls were made.

That full scan, decode plus both scoring passes plus report write, took between 0.6 and 1.4 seconds wall time across several runs on this machine. The two consistent-character pairs in the same fixture set score high and correctly go unflagged: mei_shot01.mp4 vs mei_shot02.mp4 at 0.9975 similarity, and aiko_shot01.mp4 vs aiko_shot02.mp4 at 0.9906. The deliberately inconsistent pair, kenji_shot01.mp4 vs kenji_shot02.mp4, scores 0.7709 and correctly gets flagged against the 0.88 threshold. On the physics side, calm-baseline.mp4 (smooth motion throughout) tops out at roughly 1.14x its own local baseline and stays unflagged, while action-discontinuity.mp4 (one deliberate abrupt jump) hits 8.25x and 8.32x and gets flagged against the 3x multiplier. Every one of these numbers came from the command above; the full raw diff values live in CHANGELOG.md.

Every flag carries a clip name, a numeric score, and a plain-language reason, so you or your QA reviewer can see exactly why a shot got flagged.

Quickstart

git clone https://github.com/RudrenduPaul/ContinuityGuard.git

cd ContinuityGuard npm install npm run build

scan the fixture clips bundled with this repo

node dist/cli.js scan src/score/testdata/clips

or point it at your own generated-clips folder

node dist/cli.js scan ./generated-clips/ --json > report.json

scan walks a target directory of video clips, decodes them locally via ffmpeg, computes per-shot character-consistency embeddings and a physics-plausibility heuristic, and writes a structured report in both human-readable and JSON form. Nothing it reads or computes ever leaves the machine it runs on.

CLI reference

Real, current --help output from the built CLI:

$ node dist/cli.js --help

Usage: continuityguard [options] [command]

Free, local-first CLI that scores already-generated AI short-drama clips/frames for character-consistency and physics-plausibility problems. Zero network calls.

Options: -V, --version output the version number -h, --help display help for command

Commands: scan [options] scan a directory of generated clips for character-consistency and physics-plausibility flags help [command] display help for command

$ node dist/cli.js scan --help Usage: continuityguard scan [options]

scan a directory of generated clips for character-consistency and physics-plausibility flags

Arguments: directory directory of video clips to scan

Options: --json print the full machine-readable JSON report to stdout instead of a terminal summary --fps frame sample rate for ingestion (default: 2.3) --out path to write the JSON report file to (default: "./continuityguard-report.json") -h, --help display help for command

Naming your clips so CG02 can track characters

CG02 infers which character a clip belongs to from its filename, using a _ . convention (for example mei_shot01.mp4, mei_shot02.mp4). Clips sharing a character prefix are compared against that character's first-seen shot. There is no industry-standard character-tagging metadata format across AI short-drama pipelines, so ContinuityGuard currently reads it from the filename instead of requiring a separate manifest. Clips that don't match the convention are still decoded and scored by CG03, just not compared for character consistency.

MCP Server

ContinuityGuard ships a Model Context Protocol (MCP) server, so an MCP-speaking agent (Claude Desktop, Claude Code, or any other MCP client) can drive a scan directly instead of you invoking the CLI by hand. It's part of the Python distribution, as an optional extra:

pip install "continuityguard-cli[mcp]"

Add it to your MCP client's config (for example Claude Desktop's claude_desktop_config.json):

{

"mcpServers": { "continuityguard": { "command": "continuityguard-mcp" } } }

The server exposes one tool, run, which shells out to the real continuityguard CLI with the argument list you pass it and returns a structured result (parsed JSON when the command produced it, otherwise raw stdout/stderr). Every failure mode -- a bad argument, a missing ffmpeg, a timeout -- comes back as a {"error": ...} result instead of crashing the server. Example call:

{"tool": "run", "args": {"args": ["scan", "./clips", "--json"]}}

which returns the same structured report continuityguard scan ./clips --json would print, under a result key.

Known limitations (read before trusting a flag)

• Character-consistency scoring is best-validated on photorealistic content. ContinuityGuard currently uses a generic ImageNet-pretrained visual-similarity embedding (MobileNetV2, see src/score/models/NOTICE.md for the reasoning behind that choice). Its accuracy on stylized or anime-adjacent character designs, which describes most short-drama content, is genuinely unverified. Treat a flag on stylized footage as a prompt to look closer before you trust it.
• The consistency embedding measures general visual similarity: color, texture, and coarse shape between crops. That's real signal on photorealistic faces, though weaker than a dedicated face-recognition embedding would give you. On stylized designs it's weaker still, and unvalidated.
• Physics-plausibility scoring is a frame-to-frame diff heuristic. It compares motion between consecutive frames against a shot's own local baseline and flags outliers for human review; it makes no attempt to simulate real-world physics. Expect both false positives (legitimate fast motion, stylized jump-cuts) and false negatives (subtly implausible motion that stays under the threshold).
• Thresholds are calibrated on a small, fully synthetic fixture set (solid-color clips, no real faces or recorded motion). See CHANGELOG.md fo