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 <directory>. 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 <directory>, 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] <directory>  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] <directory>

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 <fps>   frame sample rate for ingestion (default: 2.3)
  --out <path>  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 <character>_<shot-id>.<ext> 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):

Read the full README on GitHub →