Kerno: Catch breaking backend changes and unintended side effects before raising a PR

AI tools generate backend code fast, but you still need to verify it actually works.

Kerno is a validation engine that helps you catch breaking changes in your AI backend code before raising your PR. It automatically generates, runs, and maintains high-quality integration with full codebase context.

When you make changes, Kerno validates them against your real service and dependencies to catch breaking changes and unintended side effects. All directly in your terminal or IDE with instant feedback.

Installation

Run on demand with npx (no install):

npx @kerno/cli init

Or install globally:

npm install -g @kerno/cli
kerno init

Requires Node.js 18+.

Connect to Claude Code or Cursor

kerno init starts the Kerno agent (if not already running) and prints the MCP server configuration for your AI coding assistant.

Claude Code — run the command Kerno prints:

claude mcp add --transport http kerno http://localhost:<port>/mcp

Cursor — copy the printed snippet into .cursor/mcp.json:

{
  "mcpServers": {
    "kerno": {
      "url": "http://localhost:<port>/mcp",
      "transport": "http"
    }
  }
}

Once connected, your AI assistant can drive Kerno to generate, run, and validate integration tests against your real stack.

Commands

Run kerno with no arguments to launch the interactive shell, or kerno --help to see all options.

Global options

kerno audit

Gated by the PostHog feature flag kerno-audit (@kerno.io emails, on in env=dev, off in env=prod). The CLI sends env at flag evaluation from BACKEND_URL. Log in with a flagged account; otherwise audit is unknown.

Reads your git history and reports what changed after AI coding agents arrived. Read-only, no checkout of your repository disturbed. Minutes for a normal repository. Computed locally except the judge, which sends small source extracts to TypeSafe's decision API — see How the judge works.

cd your-repo
kerno audit

It asks two questions, because neither can be answered reliably from the repository alone:

1. When did AI coding agents arrive? It proposes a month from agent identities and Co-authored-by trailers, shows the evidence it used, and takes your correction. If its two detection rules disagree with the history, it says it cannot date adoption rather than inventing a month.
2. How much history should the comparison use? Twelve months by default. Six has given the opposite sign to twenty-four on a real repository, so prefer twelve or more.

Then it reports, with the named functions and commits behind each one:

• Reimplementation — functions written that the codebase already had.
• Complexity — branching per change, measured against the repository's own prior trend rather than a bare before/after. A result that trend already explains is marked confounded and kept out of the headline.
• Rework — later commits that rewrite a recent commit's code, and how long a change survives before it is first rewritten.

A commit with no AI trailer is reported as unknown, never as human: the AI figure is a floor on involvement, not a measurement of it. The audit does not measure defects — it reads git, never a bug tracker, so it can neither confirm nor deny anything about AI and bug rates.

The report lands in ~/.kerno/audit/runs/<name>/report.md.

How the judge works

Where a measurement is genuinely undecidable by static analysis, one closed question about one pair of things goes to a model — two function bodies, or a commit-message pair and one file's diff. It never scores a whole change and never searches your code.

Those questions go to TypeSafe's decision API, which runs on OpenAI models, reached through Kerno's Bifrost gateway and billed to your organization. Source from this repository therefore leaves your machine. Per run, at most:

Those are ceilings; --budget usually binds first. The caps themselves live in the plugins — MAX_JUDGED and MAX_QUOTE_LINES in plugins/duplication, MAX_JUDGED and DIFF_BUDGET in plugins/followups and plugins/complexity — so this table has to be re-read against them when they change.

A diff is raw git diff output, so it carries its diff --git a/<path> and ---/+++ headers: repo-relative file paths go with it, as do the commit messages. Whole files, the repository name and the codebase index do not.

If TypeSafe rate-limits part-way through a run, or the account it bills has run out of credit, the remaining questions go to an OpenAI decision model instead, through the same gateway and billed the same way. Neither a 429 nor an empty balance is a verdict, and without a fallback the run reports unjudged for everything it did not get to — measuring our concurrency and our billing rather than your repository. A rate limit diverts for a minute and then tries TypeSafe again; an empty balance diverts for the rest of the run, because nobody tops up a balance in the time an audit has left. Fallback answers are counted separately in the report and marked fallback in the ledger and trace, so a stand-in verdict is never mistaken for a primary one. OPENAI_API_KEY overrides the gateway with your own account; AUDIT_FALLBACK_MODEL picks a different model.

--trace-judge records every request and reply verbatim under the run directory, so you can read exactly what was sent rather than take this on trust. To judge nothing at all, pass --budget 0, or run without a Kerno session — every judged measure then reports itself as unjudged rather than guessed.

When a report says nothing was read

The audit parses with tree-sitter grammars that ship inside codegraph's package for your platform, and reads codegraph's index through node:sqlite, which needs Node 22. Both fail quietly: a grammar that is not installed is a legitimate state, so the run succeeds and every number is computed from a tree it never read.

kerno audit --doctor

checks each one directly — it installs codegraph if missing, indexes a throwaway repository and reads the index back, then parses a sample function with every configured grammar — and exits non-zero if anything is broken.

  ok    node:sqlite          available on v22.22.2
  ok    codegraph            ~/.kerno/audit/tools/node_modules/.bin/codegraph
  ok    codegraph index      1 symbols read back
  ok    tree-sitter grammars 16 ready: typescript, tsx, javascript, python, ...

How It Works

1. Codebase indexing

Kerno indexes your codebase to build a deep understanding of how everything works together. Kerno supports TypeScript, JavaScript, Python (Go, PHP, Ruby, Java coming soon).

2. Zero-config environment orchestration

Kerno automatically orchestrates your application and its dependencies (PostgreSQL, Redis, MongoDB, Kafka, RabbitMQ, and more) locally with zero manual configuration.

"Kerno was up and running in minutes with no manual work, and it made our API migration so much smoother. We could instantly validate that every change made by Cursor worked the way we expected, and now it's a core part of how we build." — Misch Strotz, Co-Founder & CEO, Letz AI

3. Baseline Capture & Diff Detection

Kerno captures the baseline behavior of critical paths for your REST endpoints, then compares your code changes to the baseline and flags any diffs.

What Kerno validates:

• Functional API workflows
• Contract & schema validation
• Error handling & resilience
• Authorization & authentication
• Boundary & edge cases

"Kerno saves us a lot of manual work and helps us catch side effects and issues that would definitely break our projects' backends. Our engineering team loves it." — Santiago J. Valls, Co-Founder & CTO, BeWise

4. Self-Healing Maintenance

As your app evolves, Kerno updates your tests to keep everything in sync without manual effort. Tests are added as features appear and retired as code changes—keeping your suite complete and consistent.

Why Teams Choose Kerno

• 35% fewer breaking backend changes and unintended side effects
• 3X faster feedback loops for developers, leading to fewer PR bottlenecks
• 10+ hours saved each week per developer troubleshooting integration issues post-CI

"Using Kerno with Claude Code has been a game changer. You get quick feedback with no manual effort, and it saves you a lot of time and hassle debugging integration issues post-merge." — Jonathan Bernales, CTO, Germen

Security & Privacy

• The codebase index is stored locally – Indexing is local and the index itself stays on your machine. kerno audit is the exception: when a measurement cannot be settled statically it sends source extracts, with the file paths in their diff headers, to TypeSafe's decision API — see How the judge works for exactly what and where.
• Never used for training – Your private code is strictly off-limits
• Enterprise security – SOC 2 Type II compliance in progress
• Encryption – TLS 1.2 in-transit, AES 256-bit at-rest

What kerno audit collects

The first audit on a machine shows this on screen and asks before anything runs. The answer is kept in ~/.kerno/audit/sharing.json; kerno audit --data-sharing asks again.

Uploading the run, with the quoted code behind each finding, is the default — including where there is no terminal to show the disclosure on, such as CI or a coding agent. Opting out is a flag away and the flags are listed below, but a pipeline that nobody has configured will send results and source to the organization it is signed in as. A run with no Kerno session uploads nothing, because it has nowhere to send it.

Every upload records how many quoted bodies it stripped, so "the source was removed" is a number rather than a promise. How long an upload is kept and how to have it deleted are in Kerno's privacy policy.

Requirements

• Node.js 18+
• Docker: Kerno uses Docker to create isolated environments for test execution. Please ensure Docker Desktop is installed and running on your local machine.
• Git: Kerno only supports Git repositories. Make sure your project is initialized with Git.

Learn More

• Documentation: https://kerno.gitbook.io/docs/
• Website: https://kerno.io

Questions? Join the Kerno Discord community.