Kerno

Kerno gives Codex the smallest fresh, verified repository context for each task—then expands from evidence, invalidates stale beliefs, and routes each phase transparently.

Comment

Kerno — the context control plane for Codex

Coding agents are increasingly capable, but they repeatedly pay a hidden tax: rediscovering the same repository, reopening unchanged files, carrying stale assumptions across branches, and using the same model and reasoning level for every phase of a task.

Kerno asks a more precise question:

What is the smallest, freshest, verified set of repository knowledge Codex needs to complete this task correctly?

Inspiration

The difficult part of agentic coding is often not generating code. It is maintaining the right beliefs about a changing codebase.

Repository search can find text that looks relevant, but similarity alone does not tell an agent:

  • why a file is needed;
  • whether an architectural belief is still fresh;
  • what source evidence supports it;
  • what change would invalidate it;
  • whether a test proved the supplied context sufficient;
  • or whether a stronger model is justified for a particular phase.

We wanted a context system capable of admitting that its first answer was incomplete, repairing that answer from evidence, and proving the final result.

What Kerno does

Kerno is a local-first context intelligence and model-orchestration layer for Codex.

It creates a closed loop:

Task → classification → minimal context capsule → Codex action → test/runtime evidence → targeted expansion or invalidation → verified result

For each task, Kerno:

  1. Incrementally indexes repository files, symbols, imports, tests, configuration, hashes, Git state, branches, and worktrees.
  2. Classifies the task and estimates its complexity, uncertainty, blast radius, and risk.
  3. Builds a bounded context capsule instead of dumping the repository.
  4. Explains every selected item with:
    • file or symbol;
    • freshness;
    • confidence;
    • estimated token cost;
    • context-value score;
    • reason for inclusion;
    • provenance;
    • invalidation conditions.
  5. Uses failing tests or runtime contradictions to expand context selectively.
  6. Invalidates memories and capsules when their files, symbols, branches, commits, or supporting evidence no longer match.
  7. Recommends models in Plugin Mode and performs actual phase-level routing through Codex App Server in Orchestrator Mode.
  8. Runs final verification in a fresh, independent review thread.
  9. Records model requests, usage, tools, tests, outcomes, limitations, and benchmark evidence without turning missing data into zero.

Kerno is not generic repository RAG. Retrieval is only one step. The product’s core is evidence maintenance: why context is trusted, what could falsify it, and how the system responds when reality proves it incomplete.

The working demo

The canonical task is a realistic cross-module refund bug:

A retried refund.succeeded webhook can credit a customer twice if the first delivery commits the ledger entry but times out before the idempotency marker.

In our controlled TypeScript fixture, the initial deterministic capsule includes the handler, ledger, idempotency logic, and related tests while excluding the transaction contract.

A genuine integration-test failure exposes that missing boundary. Kerno does not expand to the entire repository—it creates a child capsule containing only the missing transaction evidence.

The deterministic replay then applies the pre-registered acceptance patch, three assertions pass, and a later source-hash change marks the original capsule stale.

The dashboard makes the entire sequence inspectable:

  • initial evidence;
  • excluded candidates;
  • the failing test;
  • targeted context expansion;
  • the passing result;
  • routing evidence;
  • independent review;
  • and source-backed invalidation.

The replay is persistently labeled as deterministic fixture evidence. Separately retained App Server evidence is labeled independently and is never presented as part of the replayed coding run.

How we built it

Kerno is a strict TypeScript and npm-workspaces monorepo containing:

  • a Git-aware incremental indexer;
  • JavaScript/TypeScript and Python parsers;
  • a lower-confidence generic text fallback;
  • a SQLite/WAL state store for the local daemon;
  • a portable process-scoped plugin store with serialized owner-local settings;
  • an evidence-backed context and memory engine;
  • 16 strictly validated MCP tools;
  • a locally installable Codex plugin and Context skill;
  • a CLI and loopback HTTP/SSE daemon;
  • a Codex App Server orchestration adapter;
  • an independent review workflow;
  • a React/Vite evidence dashboard;
  • and a reproducible benchmark exporter.

The indexer uses repository identity, worktree state, hashes, syntax-derived symbols, imports, test relationships, lexical retrieval, and typed graph edges.

It honors .gitignore and .kernoignore, skips symlinks and oversized or binary files, and never executes repository scripts while indexing.

Inside Codex, the installed plugin contributes:

  • the Kerno plugin card;
  • starter prompts;
  • the Kerno Context skill;
  • 16 structured MCP tools;
  • and structured repository, capsule, routing, timeline, onboarding, and settings results.

The richer repository, capsule, routing, invalidation, timeline, and benchmark experience is provided by the local React dashboard.

Kerno includes a tested MCP component resource, but inline Codex panel rendering is not claimed because the current local plugin does not have a registered Codex app identity.

Kerno remains local-first. There is no mandatory hosted backend, vector database, source upload, paid third-party service, or default telemetry.

The hosted website is a read-only replay. It receives no repository source.

How Codex was used

Codex was the primary engineering collaborator throughout the build.

It helped:

  • inspect supported Codex interfaces;
  • implement and revise the monorepo;
  • generate focused tests;
  • exercise the plugin and MCP surfaces;
  • run App Server probes;
  • analyze benchmark artifacts;
  • investigate concurrency and rendering failures;
  • and correct problems exposed by type checking, security tests, browser tests, independent reviews, and real runtime output.

Focused review agents audited hackathon compliance, Codex capability boundaries, system architecture, security, product UX, evaluation integrity, and submission readiness.

The root Codex task reconciled their findings, verified reported issues, and owned the final implementation and claims.

Human decisions controlled the product thesis, architecture, scope, evidence semantics, security boundaries, visual identity, benchmark fairness rules, and which claims had to be rejected or qualified.

How GPT-5.6 was used

GPT-5.6 was used in the primary Codex implementation workflow for architecture, implementation, debugging, security review, and release validation.

Kerno also dynamically discovered GPT-5.6 models through the live Codex App Server catalog and submitted explicit phase requests.

In the retained full-system run, Kerno requested:

  • gpt-5.6-sol/low for implementation;
  • gpt-5.6-sol/ultra for final verification.

Those turns completed, their tests passed, and independent review passed.

However, the runtime did not emit a separate effective-model or reroute event. Kerno therefore labels the routes requested-unconfirmed rather than claiming an effective model it cannot independently prove.

That distinction is a core product principle:

Recommendation, request, and observed execution are different facts.

Technical challenges

The hardest challenges were:

  • separating plugin recommendations from real parent-model control;
  • packaging a portable MCP server without depending on native SQLite inside the plugin cache;
  • preventing source text and test output from becoming trusted instructions;
  • safely sharing local settings across concurrent Codex tasks;
  • preventing repeated host updates from causing focus loss or panel flicker;
  • invalidating repository knowledge conservatively across files, symbols, commits, branches, and worktrees;
  • deriving metrics only from observable App Server artifacts;
  • isolating benchmark conditions with authentication-only temporary Codex profiles;
  • preserving failed and unfavorable benchmark runs;
  • and creating a reliable replay without presenting it as a live model run.

Several designs were rejected after evidence contradicted them.

Caller-provided “verified” flags were removed because they could promote unsupported conclusions.

Early transaction implementations were rejected after independent review exposed process-local state that could not survive restarts.

Historical benchmark pairs were downgraded to fairness-unverified when their profile provenance proved insufficient.

Load testing also exposed transient shared-settings contention and destructive embedded-panel rerenders. Kerno now uses bounded lock acquisition, atomic read-modify-write settings updates, snapshot deduplication, focus preservation, single-flight actions, stale-response rejection, and bounded MCP call timeouts.

What we measured

Kerno retains 16 real benchmark runs: eight strengthened artifact-derived runs and eight earlier legacy attempts.

The current context-controlled evaluation contains three mechanically fairness-valid pairs. Each pair uses the same task, starting commit, permissions, model, and reasoning effort across baseline and Kerno conditions.

Task Correctness result Baseline observed tokens Kerno observed tokens
Refund debugging Both passed 3 tests; 0 review findings 88,788 33,952
Refund interface change Both passed 4 tests; 0 review findings 103,661 51,768
Python retry refactor Both failed; 1 review finding each 103,783 50,757

The failed Python task remains in the report. Kerno does not remove runs because they are unfavorable.

A separate full-system routing experiment also passed tests and independent review in both conditions. It recorded:

  • 82,053 observed tokens for the plain workflow;
  • 50,800 observed tokens for Kerno phase routing.

These are single-run case studies, not generalized productivity claims.

Exact cost is not reported.

Metrics the runtime could not defensibly expose—such as complete file-read coverage—remain unavailable rather than being presented as zero.

Accomplishments

  • A working failure → targeted expansion → passing test → invalidation loop.
  • An installable Codex plugin with one Context skill and 16 MCP tools.
  • Real App Server model discovery and explicit phase requests.
  • Transparent recommended, requested, effective, and unavailable route states.
  • Fresh independent review threads.
  • Branch-, commit-, file-, worktree-, and symbol-aware invalidation.
  • A complete warm light/dark evidence dashboard with accessibility checks.
  • 76 deterministic unit, contract, integration, and security tests.
  • 12 Playwright flows, including three accessibility-focused flows.
  • A two-process concurrency regression that completed 80 contending plugin calls without an INDEX_BUSY failure.
  • An earlier release-candidate commit that passed fresh-clone macOS judge-path validation.
  • A latest reliability patch that passed the complete local clean-room-equivalent gate.
  • Zero dependency vulnerabilities in the tested release candidate.
  • A public, credential-free, read-only replay at https://itkerno.site.

What we learned

Context quality is falsifiable. A failing test can prove that a context capsule is incomplete.

Model routing also requires precise language. A requested model is not automatically an independently confirmed effective model.

Local-first tools still need concurrency discipline. Multiple Codex tasks can share settings and plugin resources even when their working state is isolated.

Product truth is also a UX requirement. Replay data, live evidence, estimates, unavailable values, and requested models must remain visibly distinguishable.

Most importantly, correctness must come before a token-reduction headline.

A smaller context is useful only if the resulting change is correct, reviewable, and supported by evidence.

What is next

The next step is to repeat the current benchmark tasks to improve statistical confidence, validate additional platforms only when they can be tested, and add optional language parsers and embeddings without weakening provenance or invalidation.

A future registered Codex app surface could render Kerno’s component directly inside supported Codex hosts. Until that integration is implemented and observed, Kerno keeps the current product boundary explicit: structured plugin results inside Codex and the full evidence tracker in the local dashboard.

The long-term vision is for Kerno to become the truth-maintenance layer between a changing repository and the coding agents working on it.

Right context. Right model. Every task.

Built With

  • codex
  • codex-app-server
  • codex-plugins
  • developer
  • git
  • github-actions
  • gpt-5.6
  • http
  • lezer
  • local-first
  • model-context-protocol
  • node.js
  • npm-workspaces
  • playwright
  • react
  • server-sent-events
  • sqlite
  • typescript
  • typescript-compiler-api
  • vercel
  • vite
  • vitest
  • zod
Share this project:

Updates