supercov-cli 1.0.0

Code quality and coverage for coding agents

Supercov tells your coding agent what to fix and what to test. It scores your code quality with Jev, runs the test command you already use, and turns uncovered paths into small, actionable queries. Your agent picks a target, writes a focused test or a focused refactor, proves what improved, and keeps going.

Coverage needs no account, config file, import, custom reporter, or hosted service. Supercov is local, free, open source, and MIT licensed. Quality uses Jev and needs a key.

Website · Documentation · npm · GitHub

Supported by Supercorp.

Agent workflow: ask your coding agent to add a test in your own project, with a recorded example to follow along.

Score your code

export TYPESAFE_API_KEY=...   # get one at https://typesafe.ai
npx supercov quality

No arguments and no configuration. It finds your source, asks Jev a set of yes/no questions about each file, and does the arithmetic itself, so every part of a score is a claim you can check against the file.

Quality weak (3.8/10) over 163 files.
  11 good, 52 fair, 100 weak.

Weakest:
  weak  runtime/python/supercov_runtime.py
        long_method 0.96, deep_nesting 0.92, complex_conditional 0.89, +9 more
  weak  crates/supercov-engine/src/assertion_store.rs
        long_method 0.96, deep_nesting 0.91, complex_conditional 0.86, +8 more

Narrow to what fired, read one file in full, or review a change:

npx supercov quality gaps
npx supercov quality file src/server.ts
npx supercov quality patch                    # your uncommitted work, or your branch
npx supercov quality patch --annotate github  # workflow annotations, no token

Jev charges for what it reads and nothing for what it writes, so a megabyte of source costs a little over a cent. Answers are cached by content, so a second run pays only for what changed. See Understanding quality.

Start with the suite you already have

npx supercov -- npm test

Other ways in, all the same binary at the same version: brew install supercorp-ai/tap/supercov, or for a Go project go run github.com/supercorp-ai/supercov/cmd/supercov@latest.

Everything after -- is your test command. Supercov runs it without changing your source, tests, runner configuration, or normal build output.

Then read the result and ask what is still uncovered:

npx supercov runs latest

run run_7fc676ba671d42be
command: npm test

Coverage
  Lines      100.00% (5/5)
  Branches   66.67% (4/6)
  MC/DC      33.33% (1/3)

npx supercov runs latest gaps --limit 10

Coverage gaps — only files with unresolved obligations

src/pricing.js
  uncovered: lines 0  statements 1  functions 0  branch outcomes 0  MC/DC conditions 2

After your agent adds a test, rerun the complete suite and prove the gain:

npx supercov -- npm test
npx supercov diff <previous-run-id> latest

Use whichever complete test command the repository already trusts:

npx supercov -- npx playwright test
npx supercov -- pnpm test:e2e
npx supercov -- cargo test
npx supercov -- cargo nextest run
npx supercov -- pytest
npx supercov -- python -m unittest
npx supercov -- bundle exec rspec

Map what assertions check

Each normal test run creates an assertion map automatically. An agent can optionally fill in what the assertions check:

npx supercov runs latest assertions --json
# Pin the returned run ID. Inspect assertions and the source that ran:
npx supercov runs <run> assertion <assertion-id>
npx supercov runs <run> source src/example.ts
# Edit assertions.json, then validate and acknowledge:
npx supercov runs <run> assertions validate --json
# Copy examined expectedBasis tokens into assertions.json; save again.
npx supercov runs <run> assertions check --require-mappings --json
npx supercov runs <run>  # includes the assertion percentage in the regular report

After code or tests change, run the same test command again. Supercov reuses the newest available map for that command and language and identifies dirty flows. Rust owns validation, change tracking and reporting; the agent supplies semantic reasoning. The score is agent-assessed and separate from MC/DC. See assertion maps for the format and JS/TS limits, or run supercov docs assertion-agent for the agent workflow. supercov assertions schema exports the editor schema; assertions validate --file <path> checks JSON syntax.

Give Supercov a job

Paste one of these prompts into Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, or any coding agent that can run terminal commands.

Write the first useful test

Measure code coverage with `npx supercov`. Use the coverage evidence to choose
one useful missing test. Only edit tests. Run the repository's complete test
suite through Supercov again and report what improved.

Use leftover tokens on coverage

Measure code coverage with `npx supercov` and write tests til 100%. Only edit
tests. Keep going while useful gaps remain.

Run the repository's complete test suite through Supercov. Use
`npx supercov runs latest gaps --limit 5` to choose one useful target at a
time. Write a focused test, rerun the same complete suite, and use
`npx supercov diff <previous-run-id> latest` to verify the gain.

Never weaken assertions or change application code to make coverage easier.
Stop if the suite fails, the evidence is incomplete, or no useful gaps remain.

The agent loop

1. Run the real suite. Supercov executes the command after -- in an isolated workspace.
2. Find one useful gap. Short, paginated queries show uncovered files, lines, branches, decisions, and value paths without loading a large HTML report into context.
3. Write one focused test. The coding agent changes tests—not application code or coverage configuration.
4. Rerun and prove the gain. diff shows exactly what the new test covered.
5. Repeat while useful gaps remain. Failed tests, incomplete evidence, or ambiguous scope stay visible instead of being rounded away.

Supercov supplies the coverage signal and evidence. It does not host, schedule, or replace your coding agent.

Use leftover tokens on coverage

Before a reset—or overnight—turn idle agent time into coverage that stays with the repository. Each pass closes a small number of useful gaps and finishes with evidence that the tests still pass and coverage improved.

Use it in a software factory

Add Supercov as a repeatable quality loop in an automated software factory. Your factory schedules the work; Supercov gives each agent a bounded next task and an immutable record of the result.

Every pass runs the real suite, chooses an uncovered path, writes a focused test, reruns, and proves the gain. Fresh executable evidence lets agents keep iterating around the clock while failed tests and regressions stop the loop before they ship.

Coverage agents can act on

From lines and branches to MC/DC, every gap becomes a concrete test target. Supercov measures:

• lines, statements, functions, and branches;
• MC/DC independence witnesses;
• optional-chain, default-value, and logical-assignment paths;
• try/catch and zero-iteration control-flow paths; and
• per-test provenance where the runner exposes exact test boundaries.

The denominator comes from source structure before the run, so adding or removing tests cannot silently change what 100% means. Ambiguous source scope, uninstrumented code, and missing evidence remain visible as completeness blockers.

Install for your language

Measuring a project should not start by installing another language. The same binary, at the same version, from one release:

npx supercov -- npm test                                 # npm
uvx --from supercov-cli supercov -- pytest               # PyPI
gem install supercov && supercov -- bundle exec rspec    # RubyGems
cargo binstall supercov && supercov -- cargo test        # crates.io
go run github.com/supercorp-ai/supercov/cmd/supercov@latest -- go test ./...   # Go
brew install supercorp-ai/tap/supercov && supercov -- ./gradlew test           # Homebrew

pip install supercov-cli and gem install supercov install a wheel or gem that carries the binary for your platform; nothing is compiled. cargo binstall downloads that same binary from the GitHub release, while plain cargo install supercov builds it from source and needs Rust 1.95.

A Go project needs Go and nothing else. Like any go run with a version suffix it resolves by module path and ignores the go.mod in your current directory, so it neither needs nor touches your module.

Java and Kotlin have no registry of their own here, so a JVM project takes the binary directly -- Homebrew above, npx if Node is already present, or the platform archive from the latest release. Maven and Gradle are driven as your test command, not as a plugin. Supercov adds the JUnit Platform launcher its measurement needs to the build file inside its own isolated workspace copy -- your pom.xml or build.gradle is never edited.

Supported languages

Supercov requires Node.js 22 or newer. Rust support currently uses Rust 1.95; cargo-nextest 0.9.138 and 0.9.140 are supported. Python support requires CPython 3.12 or newer and measures pytest and unittest runs. Ruby support requires Ruby 3.3 or newer (3.4 or newer for full measurement) and measures RSpec, Minitest, test-unit and Cucumber runs. Go support requires Go 1.22 or newer and measures go test. Java and Kotlin support requires a JDK 17 or newer with Maven or Gradle, and measures every JUnit Platform engine -- JUnit 5, JUnit 4 through Vintage, Kotest and Spock -- as well as TestNG.

Supported operating systems and architectures

The CLI is a single native binary. npx supercov selects the build for the machine it runs on; nothing is compiled during installation.

JavaScript, TypeScript, Python, Ruby, Rust, Go, Java and Kotlin suites are verified on Linux, macOS and Windows -- CPython 3.12, 3.13 and 3.14, Ruby 3.3, 3.4 and 4.0, and Go 1.22 and 1.25 on every one, and JDK 17 and 21 on every one that has them (Temurin publishes no 17 for arm64 Windows, so that pairing is 21 alone). Containers, VMs, and remote executors run the same Linux builds. Every release publishes the same binaries to npm, PyPI (supercov-cli, a wheel per platform) and RubyGems (supercov, a gem per platform except arm64 Windows, which Ruby has no platform for), and the source to crates.io (supercov).

Supported test suites

Supercov uses exact per-test attribution where an adapter is available. For other supported runners, it reports aggregate structural coverage instead of guessing which test covered a path.

Supercov works with Vite, Next, Turbopack, Webpack, esbuild, SWC, and projects with no build step. One command can collect evidence from several supported runners into a single run.

See Supported languages and test suites for exact compatibility and attribution boundaries.

Read the result

# Recent runs and the latest summary
npx supercov runs --limit 5
npx supercov runs latest

# The most useful open coverage obligations
npx supercov runs latest gaps --limit 10

# Details for a file or source location
npx supercov runs latest file app/checkout/session.ts
npx supercov runs latest decision app/checkout/session.ts:64
npx supercov runs latest line app/checkout/session.ts:64

# What changed between two runs
npx supercov diff <previous-run-id> latest

Collections accept --limit and --offset and print a copyable next-page command. Machine-readable output is available with --json when an integration needs it.

Local, private, and zero-edit

Everything Supercov writes lives under one hidden .supercov/ directory: run evidence in .supercov/runs/<run-id>/ and the isolated build cache in .supercov/workspaces/. It ignores itself in Git, so there is nothing to add to your .gitignore.

The Supercov CLI does not contact a Supercov service during a coverage run. Package tools such as npx may contact the npm registry to download Supercov when it is not already cached.

Supercov does not rewrite your source files, tests, imports, reporter list, runner configuration, dependency tree, or normal build output. An existing user-created supercov/ directory is never adopted.

npx supercov clean --dry-run   # preview cleanup
npx supercov clean --keep 20   # keep the 20 newest runs
npx supercov clean             # remove all runs and the build cache

Documentation

• Getting started
• Understanding quality
• Agent workflow
• Understanding assertions
• Troubleshooting
• CLI reference
• Supported languages and test suites
• Understanding coverage
• Runs and evidence
• Files, privacy, and cleanup
• Trusting a result
• Speed and storage

Free and open source

MIT licensed. Inspect, extend, and run it anywhere.