# continuityguard
**Category:** 💻 Developer Tools
**Repository:** https://github.com/RudrenduPaul/ContinuityGuard
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/continuityguard
## Description
Wraps the ContinuityGuard CLI as a single generic MCP tool for video-clip continuity scans.
## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"continuityguard": {
"command": "npx",
"args": ["-y","continuityguard"]
}
}
```
## Documentation & README
# ContinuityGuard
[](https://github.com/RudrenduPaul/ContinuityGuard/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)
[](https://www.npmjs.com/package/continuityguard-cli)
[](https://pypi.org/project/continuityguard-cli/)
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.
```bash
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:**
```bash
pip install continuityguard-cli
```
See [`python/README.md`](https://github.com/RudrenduPaul/ContinuityGuard/blob/HEAD/python/README.md) for the Python-specific
quickstart, CLI reference, and library API.
**TypeScript/npm:**
```bash
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):
```bash
$ 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
```bash
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:
```bash
pip install "continuityguard-cli[mcp]"
```
Add it to your MCP client's config (for example Claude Desktop's `claude_desktop_config.json`):
```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:
```json
{"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` for the exact numbers and the command that produced them. This is a real, reproducible starting point, calibrated from two synthetic pairs rather than a large labeled dataset. Expect the numbers to move as real-world reports come in.
- **The `_` filename convention is a current simplification**, built for a category that has no standard character-tagging metadata format yet. A clip that doesn't follow it still gets scored for physics; its consistency comparison is simply skipped.
- **Requires a system `ffmpeg` install.** ContinuityGuard checks for it at startup and prints the exact install command for your OS if it's missing (for example `brew install ffmpeg` on macOS, `apt install ffmpeg` on Debian/Ubuntu). It does not currently bundle a static ffmpeg binary. A bundled per-platform build would be materially larger than this project's own dependency footprint and would inherit ffmpeg's own shifting LGPL/GPL licensing terms depending on which codecs are compiled in. Depending on a system install keeps this package small and its licensing surface simple.
- **Pinned to TypeScript 6.x, not yet 7.x.** TypeScript 7 (the native/Go compiler rewrite) dropped support for the CommonJS-interop default export that `typescript-eslint`'s peer range still requires as of its latest release (8.66.0, which still declares `typescript: >=4.8.4 <6.1.0`). This isn't a vulnerability, just an ecosystem-wide compatibility gap: the whole `typescript-eslint` toolchain hasn't shipped TS7 support yet, so this project will stay on TypeScript 6.x until it does.
## How it compares
There is no widely-used, directly comparable tool that combines local character-consistency scoring and a physics-plausibility heuristic in one zero-network CLI built specifically for reviewing already-generated AI short-drama output. The closest real, verified projects sit either one layer up (academic benchmarks for scoring video-generation models) or one layer down (general face-embedding libraries you'd have to wire up yourself):
| Project | Stars | Last activity | License | What it actually is | How it compares |
|---|---|---|---|---|---|
| [Vchitect/VBench](https://github.com/Vchitect/VBench) | 1,718 | Mar 2026 | Apache-2.0 | CVPR 2024 academic benchmark suite that scores video-generation models across 16 dimensions, including a DINOv2-based "subject consistency" metric and a motion-smoothness metric, aggregated across many generated clips | The closest mechanism match: it also scores subject consistency and motion quality on already-generated video. It's a GPU-dependent research benchmark for evaluating a generation model in aggregate, not a lightweight local CLI built to give one creator a per-clip QA report on their own footage. |
| [serengil/deepface](https://github.com/serengil/deepface) | 23,204 | Jun 2026 | MIT | Widely used, actively maintained Python library for face verification, embeddings, and facial attribute analysis | A component library for face-embedding similarity, not a video-native or short-drama-specific tool. Useful as a building block, but ships no physics check, no clip decoding, and no packaged report format of its own. |
| [deepinsight/insightface](https://github.com/deepinsight/insightface) | 29,406 | Jul 2026 | No single machine-readable LICENSE in the repo; project docs describe MIT-licensed code with non-commercial restrictions on some pretrained models | State-of-the-art 2D/3D face analysis toolbox (detection, recognition, alignment) | Same category as DeepFace: a component library, not an end-to-end QA CLI. No physics-plausibility check, no report layer. |
| [evalcrafter/EvalCrafter](https://github.com/evalcrafter/EvalCrafter) | 195 | Oct 2024 | None listed | CVPR 2024 research framework benchmarking video-generation models on visual quality, motion quality, and text-video alignment across 700 prompts | Adjacent research tool with no commits in roughly two years. Built to benchmark generation models with a heavy multi-metric research stack, not to give a fast local QA pass on a folder of already-generated clips. |
Star counts and last-activity dates above were pulled live from the GitHub API while writing this table.
## What is ContinuityGuard, and why does it exist
ContinuityGuard is a free, open-source, local-first CLI. It ingests a directory of already-generated video clips from any AI short-drama pipeline, decodes them with `ffmpeg`, and runs two scoring passes: a character-consistency check (cosine similarity between MobileNetV2 embeddings of same-named-character crops across shots, best-validated on photorealistic content and unverified on stylized or anime-adjacent designs) and a physics-plausibility heuristic (frame-to-frame diff ratios against a shot's own local motion baseline, a heuristic that flags shots for human review rather than a physics simulator). It writes both a human-readable terminal report and a machine-readable JSON report, and it never makes a network call while doing any of it.
It exists because AI short-drama generation is shipping hundreds of new titles a day, and every one of those titles is assembled from many separately generated shots. Generation models drift: character faces shift slightly between cuts, and motion sometimes jumps in a way that reads as physically wrong the moment a human watches it. Catching that before a re-render saves the cost of redoing the shot from scratch.
ContinuityGuard is a QA layer, not a generator, and that is the point. It sits on top of whatever pipeline already produced your footage instead of locking you into one, it runs entirely on your own machine so unreleased footage never has to leave it, and it is free with no account or API key required. A generation platform's own built-in QA, if it has one, only ever sees its own output; ContinuityGuard works the same way whether your clips came from an open-source pipeline, a commercial one, or a mix of both on the same project.
## Local-only, always
Your unreleased footage never leaves your machine. Every clip is decoded locally via `ffmpeg`, every embedding is computed locally via a bundled offline ONNX model, and the report is written to a local file. No account, no API key, no upload step, for any frame. `npm run verify:zero-network` proves this empirically: it monkey-patches every network entry point Node exposes and runs a real scan against this repo's own fixtures, and it would fail loudly if anything tried to reach the network. It runs in CI on every push. See `CHANGELOG.md` for the exact result.
## FAQ
**Is this validated for anime or stylized AI-generated characters?**
No. Character-consistency scoring is best-validated on photorealistic content. Its accuracy on stylized or anime-adjacent designs, which is most short-drama content, has not been independently benchmarked yet. Treat every flag on stylized footage as a prompt to look closer. This is the single most important caveat in this repo; see "Known limitations" above.
**Does the physics check actually understand physics?**
No. It's a frame-to-frame motion-discontinuity heuristic. It compares each shot's frame-to-frame diffs against that shot's own local baseline and flags outliers for human review, with no attempt to model real-world physics. It will produce false positives on legitimate fast motion or stylized jump-cuts, and false negatives on subtle implausible motion that stays under the threshold.
**Do I need a GPU?**
No. Everything runs on CPU via `onnxruntime-node`, using a small (14MB) MobileNetV2 model. The 8-clip fixture scan above completes in under two seconds on an ordinary laptop.
**Does this upload my clips anywhere?**
No. That's mechanically enforced: `npm run verify:zero-network` patches every network entry point Node exposes and runs a real scan, and the check fails loudly if anything tries to reach the network. It runs on every CI push.
**Why do I need to install ffmpeg separately instead of it being bundled?**
A bundled static ffmpeg binary would add tens of megabytes per platform to this package and would inherit ffmpeg's own licensing terms, which shift between LGPL and GPL depending on which codecs are compiled in. ffmpeg is close to ubiquitous on developer machines already, so ContinuityGuard depends on a system install and checks for it at startup with a clear, OS-specific error if it's missing.
**Is this on npm yet?**
Yes. `npm install -g continuityguard-cli` installs it today. The Python package is also on PyPI (`pip install continuityguard-cli`), using the same scoring logic and the same bundled model -- see [`python/README.md`](https://github.com/RudrenduPaul/ContinuityGuard/blob/HEAD/python/README.md).
**Will a big video-generation platform just build this into their product and make ContinuityGuard pointless?**
Possibly, and this repo says so plainly rather than hiding it: any well-funded video-generation platform could ship an equivalent check natively, since it already runs the full generation pipeline and has a direct incentive to prevent wasted render costs. ContinuityGuard's value is being free, local, and pipeline-agnostic today. Nothing here promises that stays true tomorrow.
**Can I use this in CI?**
Yes. `--json` writes a machine-readable report an agent or CI step can parse, and the whole tool runs with zero network access, so it drops into a CI job the same way any other local static-analysis step would.
**What platforms and Node versions does this run on?**
`package.json` requires Node >=22 and lists no OS restriction. The native scoring dependency, `onnxruntime-node`, ships prebuilt binaries for macOS, Linux, and Windows. You also need a system `ffmpeg` install (checked at startup, with an OS-specific install command printed if it's missing). The Python distribution (`pip install continuityguard-cli`) needs Python >=3.9 and the same system `ffmpeg` requirement, and is classified `Operating System :: OS Independent`.
**How does this compare to a face-embedding library like deepface instead of a generic ImageNet model?**
Directly, they solve different layers of the same problem. `serengil/deepface` (MIT-licensed, actively maintained) is a dedicated face-verification and embedding library; wiring it into a scan pipeline yourself would likely give more accurate character-consistency scoring than ContinuityGuard's current generic MobileNetV2 embedding, especially on stylized content. ContinuityGuard's role isn't to out-perform a dedicated face-embedding library on embeddings alone: it's the packaged CLI on top, doing ffmpeg decoding, the physics-plausibility pass, and structured report output in one zero-network command. Swapping in a stronger embedding model later is an open, tracked improvement, not a claim already delivered. See "How it compares" above for the fuller table.
**Is this free to use commercially?**
Yes. Everything in this repo is Apache 2.0, including the permissive patent grant that license carries. There's no separate commercial tier, no usage cap, and no license key. Attribution and the license notice requirements of Apache 2.0 still apply, same as any Apache-licensed dependency you'd pull into a commercial project.
## Contributing
See `CONTRIBUTING.md` for local setup for both the TypeScript package (repo root) and the Python package (`python/`), the full pre-PR checklist (lint, typecheck, coverage thresholds, `npm audit`, the zero-network verification script), and fixture-reproducibility rules. Reports of false positives or false negatives on real (not synthetic) AI short-drama footage, especially stylized or anime-adjacent content, are the single most useful contribution right now, since that's exactly the gap disclosed above.
## Documentation
- [docs/getting-started.md](https://github.com/RudrenduPaul/ContinuityGuard/blob/HEAD/docs/getting-started.md) -- install paths for both packages, your first scan, the library API.
- [docs/concepts.md](https://github.com/RudrenduPaul/ContinuityGuard/blob/HEAD/docs/concepts.md) -- what CG01-CG04 each do, and where the 0.88 / 3x thresholds came from.
- [docs/integrations/ci.md](https://github.com/RudrenduPaul/ContinuityGuard/blob/HEAD/docs/integrations/ci.md) -- wiring ContinuityGuard into a CI pipeline.
- [python/README.md](https://github.com/RudrenduPaul/ContinuityGuard/blob/HEAD/python/README.md) -- the Python package's own README (PyPI quickstart, CLI reference, fidelity notes).
## License
Everything in this repo: Apache 2.0. Free forever, no paid tier.