Coverctl

coverctl

Agent-loop coverage governance for all sorts of languages — coverage your AI coding agent calls before commit, not a dashboard you read after CI.

Works with Python, TypeScript/JavaScript, Java, Rust, Go, C#, C/C++, PHP, Ruby, Swift, Dart, Scala, Elixir, and Shell — one .coverctl.yaml, one MCP surface. Not a Go cover tool.

Get started ↓ · Languages ↓ · What it looks like ↓ · MCP tools ↓ · CLI reference ↓ · Why this exists ↓ · Community ↓

*"Our AI agents ship code fast, but they're blind to coverage policy while editing. We only see breakage in CI, after context is gone, and the same agent then guesses its way to a fix."*

Same policy model on every language: auto-detect the runner, group paths into domains, enforce mins before commit. Mock-heavy or exotic layouts may need an explicit domains: block in .coverctl.yaml.

coverctl is not a Go cover CLI: it is policy + MCP over each language's native coverage runner (vs go test -cover / pytest --cov).

Get started

brew install klarlabs-studio/tap/coverctl

Wire into Claude Code (~/.config/claude-code/mcp.json):

{

"mcpServers": { "coverctl": { "command": "coverctl", "args": ["mcp", "serve"] } } }

Ask the agent: *"Run coverctl check and tell me which domains regressed."*

For Cursor / Cline / Claude Desktop / Aider / Continue / OpenCode and other MCP clients, see docs/src/content/docs/mcp.mdx. All MCP-capable clients work; coverctl mcp serve runs in agent mode by default (3 tools: check, suggest, debt). Use --mode=ci for the full nine-tool surface.

Validate the install end-to-end:

coverctl mcp doctor   # PASS/FAIL per step with remediation

What it looks like in the agent loop

*Rendered for clarity — your client may format tool-calls differently.*

You:    Add the email-validation feature to the api domain.

Claude: I'll add EmailValidator + tests under src/api/.

[edits: src/api/email.ts, src/api/email.test.ts]

Tool call → coverctl check Result → passed: false; failing: api (78.2%, required 80%) uncovered: src/api/email.ts:42-58 (error paths)

Tool call → coverctl suggest api Result → uncovered files: email.ts (16 lines), retry.ts (4 lines)

Two error branches in EmailValidator.validate are uncovered. I'll add cases for empty-input and malformed-domain so api meets the 80% threshold before we commit.

The regression that used to surface in CI 8 minutes later is fixed in the same agent turn.

The agent does well: reads check output verbatim, calls suggest to find uncovered files, calls debt to rank smallest fixes, re-runs check to confirm.

Watch for: agents lowering thresholds in .coverctl.yaml to "fix" a failure (it's not a fix). Agents claiming coverage rose without a new check call (hallucination). Agents ignoring rejection error_code and retrying with the same input.

coverctl returns deterministic structured signals; the agent's *fix* still needs a human reading. The full contract is in docs/src/content/docs/mcp.mdx.

Why this exists

AI coding agents write code blind to coverage. They edit, you commit, the regression surfaces in CI minutes or hours later — too late to course-correct in the same session. Dashboards (Codecov, Coveralls) and raw language runners (go test -cover, pytest --cov, nyc) target humans reading numbers after the fact — not agents enforcing policy mid-edit.

coverctl is built for the agent loop (and is not a replacement for Go's cover tooling):

• Catches regressions before commit. Coverage feedback in the agent's edit turn — not minutes after CI fails. The wedge metric is regressions caught pre-commit.
• Agent-callable via MCP. Speaks MCP — the multi-vendor agent-tool standard now governed by Anthropic, OpenAI, Google, Microsoft, AWS. Works with every MCP-capable client today; works with whatever ships next without modification.
• Polyglot governance, one config. One .coverctl.yaml enforces per-domain thresholds across 15 languages. On Go repos it may *invoke* go test the way it invokes pytest elsewhere — then applies the same domain policy. Agents touch any language; coverage governance must too.
• Local-first. Your source never leaves the machine. Agent calls coverctl over stdio, not over a SaaS API. No account, no upload, no third-party dependency in the agent's reach.
• Hardened MCP surface. Input + output sanitization defends against prompt-injection through test-runner flags and hostile filenames in coverage profiles (Lethal Trifecta).

The CLI and MCP server are Apache-2.0 licensed and stay free. A hosted layer for cross-repo coverage history is on the roadmap (see docs/strategy/monetization-decision.md) — additive, not a paywall.

MCP tools

Agent mode advertises three tools (check, suggest, debt) for reliable agent tool selection. CI mode (--mode=ci) adds the rest.

MCP resources (read-only context)

Security boundaries

coverctl treats MCP traffic as untrusted in both directions, per the Lethal Trifecta threat model.

• Input boundary. Agent mode accepts typed capabilities (packages, tags, race, short, run, timeout) and rejects arbitrary runner testArgs so coverctl cannot be used as a generic command-execution MCP server. Dangerous flags (--rootdir, --cov-config, -D, -I, --require, --init-script, --node-options, ...) are also denied as defense in depth. Agent mode cannot select an alternate policy file, filter check to a subset of domains, narrow coverageScope (shrinking measurement can hide untested domains), skip the test run via fromProfile, or use incremental check (an empty diff auto-passes); repository .coverctl.yaml is authoritative and verification must execute tests against the full policy. Rejection responses use a stable schema with error_code and agent-actionable remediation. CLI invocations from a human terminal are not sanitized; the human is the trust boundary there.
• Output boundary. User-controlled identifiers flowing *back* to the agent (filenames in coverage profiles, domain names, package paths) are percent-encoded rather than destructively replaced, so distinct names stay distinct (src/über.go does not collapse into another file). Control characters, backticks, and markdown metacharacters cannot render as instructions. Prevents return-trip prompt injection through a hostile PR or attacker-named test file.

coverctl is local-first. The default install transmits nothing — no telemetry, no analytics, no source data. An opt-in --mcp-telemetry flag emits structured tool-call events to stderr for users who want to instrument their own pipelines (format documented in docs/design/mcp-metrics-spec.md). Adversarial + happy-path evals (85+ scenarios under internal/eval/scenarios/) gate every release on rejection-schema integrity and prompt-injection resistance.

Canonical intent: docs/strategy/system-intent.md. Full threat model + residual risk: docs/security/mcp-threat-model.md.

CLI reference

The CLI is the substrate behind the MCP server; humans can use it directly.

Global flags: -q/--quiet, --no-color, --ci (combines quiet + GitHub Actions annotations).

Test-execution flags

check, run, record accept toolchain flags forwarded to the underlying test runner:

Terminal flow (without an agent)

If you prefer running coverctl directly:

coverctl init      # auto-detect language + domains, write .coverctl.yaml

coverctl check # enforce policy; exit 1 on violation coverctl suggest --strategy current coverctl record

If a step fails: coverctl detect --dry-run previews init output; coverctl check -o json surfaces structured failure detail; coverctl record --commit "$(git rev-parse HEAD)" --branch "$(git rev-parse --abbrev-ref HEAD)" provides metadata explicitly in CI.

Configuration

.coverctl.yaml (schema: schemas/coverctl.schema.json):

Domains are named path groups, not language packages. match uses path globs for most languages (src/auth/**) or Go package paths when the project is Go (./internal/auth/...):

version: 1

policy: default: min: 75 domains:

• name: auth match: ["src/auth/**"] # Go equivalent: ["./internal/auth/..."] min: 90 # critical path — stricter
• name: api match: ["src/api