The machine-verifiable floor for AI-authored Python.

Deterministic gates for lint, typecheck, tests, coverage, acceptance, complexity, CRAP, mutation, deps, audit, and arch — every agent PR trips them before merge.

One command surface, local and in CI. Try it without installing — uvx or pipx run.

uvx --from interlocks il doctor

or pipx run --spec interlocks il doctor

Package: interlocks. Commands: interlocks and il.

Run your first check →

`interlocks check` — the local edit loop

$ interlocks check
interlocks v0.1.2  ·  preset=strict  ·  runner=pytest  ·  invoker=uv

── Quality Checks ──────────────────────────────────────────
  [fix]         ruff check --fix                      ok
  [format]      ruff format                           ok (2 files reformatted)

── Parallel ────────────────────────────────────────────────
  [typecheck]   basedpyright                          0 errors, 0 warnings
  [test]        pytest -q                             184 passed in 3.2s
                                                      coverage 87.4%

── Advisory ────────────────────────────────────────────────
  [deps]        deptry                                ok
  [crap]        cached (crap_max=30.0)                ok · 0 offenders

── Suppressions ────────────────────────────────────────────
  ruff : noqa              0
  basedpyright : ignore    1   interlocks/runner.py:42
  pytest.skip              2

Completed in 7.4s

Stages — when to run what

Seven stages, one CLI. Each has a narrow job and a stable contract so hooks, CI, and schedulers call the same commands you run locally.

interlocks check — after edits, before pushing fix → format → parallel(typecheck, test, acceptance when opted in) → deps advisory → cached CRAP advisory → suppressions report.
interlocks pre-commit — git pre-commit hook fix and format staged Python files, re-stage, typecheck, run tests when source changed. Skip with git commit --no-verify.
interlocks ci — pull requests and protected branches format-check, lint, complexity (lizard, CCN 15), deps, typecheck, coverage, optional arch/acceptance → blocking CRAP → optional mutation.
interlocks nightly — scheduled job coverage then mutation, always blocking on mutation_min_score. Wire via cron or a GitHub Actions schedule.
interlocks post-edit — editor / agent hook advisory ruff fix and format on changed Python files. Installed as a Claude Code Stop hook by setup-hooks.
interlocks setup-hooks — hook installer installs the git pre-commit hook and merges the Claude Code Stop hook that runs interlocks post-edit. Rerunnable and idempotent.
interlocks clean — local cleanup removes caches, build artifacts, coverage output, mutation state, and __pycache__/.

Command surface

Tasks. fix, format, lint, typecheck, test, coverage, crap, mutation, deps, audit, arch, acceptance, and init-acceptance.

Reports. trust combines coverage, CRAP, mutation, suspicious-test inspection, recent git diff, and next actions.

Utilities. doctor, init, presets, config, version, and help.

In practice

Monday morning. New Python repo, fresh from git init. No pyproject.toml gate configured, no CI pipeline, no agreed thresholds. The team wants a baseline by EOD.

You run pipx install interlocks or uv tool install interlocks, then interlocks doctor. It prints detected source and test directories, the active preset, resolved thresholds, and the two commands you need next. You commit a three-line GitHub workflow that calls 0xjgv/interlocks@v1. Locally, interlocks check runs the same gates CI will run, minus the heavy ones.

By the afternoon, the first PR lands. CI enforces lint, typecheck, tests, coverage, CRAP, deps, arch, and acceptance — all from the reusable action. Nobody edited eleven tool configs.

Result: green CI in one PR. Config: zero.

Read the docs on GitHub →