Verðandi — Context Compiler for AI Coding Agents

Your agent doesn't spend most of its budget solving the problem. It spends it looking for the problem.

Verðandi (pronounced ver-THAN-dee) reads your codebase so your agent doesn't have to. It indexes the project with the TypeScript compiler, works out which symbols the task actually touches, and hands the agent a small, bounded capsule of exactly that. The agent skips the hunt and starts on the work.

Named after the Norse Norn of the present — the one who sees what is, not what was or will be.

The problem, in one picture

WITHOUT VERÐANDI                          WITH VERÐANDI
─────────────────────────────────         ─────────────────────────────────
 Task: "fix the auth retry bug"            Task: "fix the auth retry bug"
        │                                         │
        ▼                                         ▼
 ┌──────────────────────┐                  ┌──────────────────────┐
 │ agent: ls, grep, cat │  ← tokens        │ Verðandi indexes the │  ← no model
 │ reads a file… wrong  │  ← tokens        │ repo with the TS AST │     tokens
 │ reads another…       │  ← tokens        └──────────┬───────────┘
 │ searches again…      │  ← tokens                   │
 │ finally finds it     │  ← tokens                   ▼
 └──────────┬───────────┘                  ┌──────────────────────┐
            │                              │ capsule: 3 symbols,  │
            ▼                              │ 2 files, ~250 tokens │
      starts working                       └──────────┬───────────┘
                                                      │
                                                      ▼
                                                starts working

That search is invisible on your bill. It just looks like "the task was expensive".

Related MCP server: Code Reference Optimizer MCP Server

What it actually saves

Ten real tasks, taken from commit pairs in modelcontextprotocol/typescript-sdk. Same model, same settings — baseline agent vs. the same agent with Verðandi:

Every run was independently tested, linted, typechecked and read by hand. The model's own "I verified it" was not accepted as evidence.

The spread is the honest part: savings scale with how much searching a task needs. A one-line import-order fix saves nothing and can even cost more. A bug spread across four files is where 70–80% shows up.

Not proven yet

• Quality equivalence. Task tests pass on both sides, but a third-party blind comparison score is still pending. "No quality loss" is the goal, not a finished measurement.

• Generality. Ten tasks, one repository, TypeScript only. T11–T40 and a second independent labeller remain open.

Published because a benchmark that only reports its wins is not a benchmark.

How it works

  your task ──▶ ┌─────────────────────────────────────────────┐
                │ 1. INDEX     TypeScript compiler API:       │
                │              symbols, imports, call graph   │
                ├─────────────────────────────────────────────┤
                │ 2. SELECT    direct matches, plus 1-hop     │
                │              neighbours in the call graph   │
                ├─────────────────────────────────────────────┤
                │ 3. BUDGET    200–300 tokens normally;       │
                │              wider when confidence is low   │
                ├─────────────────────────────────────────────┤
                │ 4. SERVE     capsule over MCP, or injected  │
                │              straight into the prompt       │
                └──────────────────┬──────────────────────────┘
                                   ▼
                            agent does the work
                                   │
                ┌──────────────────▼──────────────────────────┐
                │ 5. PATCH     content-hash preconditions,    │
                │              atomic multi-file, rollback    │
                └─────────────────────────────────────────────┘

When retrieval confidence falls below 0.72, Verðandi silently escalates to a wider budget instead of handing over a thin capsule and hoping. After three attempts it stops and hands the task to a human rather than spending more budget on guesses.

Quick start

npm install
npm run build
npm test

Then choose how to use it.

As an MCP server

node bin/verdandi-context-compiler setup codex   # prints the registration command
node bin/verdandi-context-compiler status

Supported: codex, claude, opencode, natureco, hermes, openclaw, kimi, glm, antigravity.

Injected into the prompt

./run_with_capsule.sh <agent> <project-root> "Your task"

Auto-inject supports natureco, hermes, codex, claude, opencode, openclaw, kimi, glm. antigravity works as an MCP server but has no auto-inject entry yet.

As a standalone agent

verdandi-agent "Fix the import order" --project ./project --model gpt-4o --api-key "$VERDANDI_API_KEY"

Environment: VERDANDI_API_KEY, VERDANDI_MODEL, VERDANDI_BASE_URL, VERDANDI_REQUEST_TIMEOUT_MS, VERDANDI_CODEX_MODEL. Legacy URDR_* names still work.

The five tools

Safety

This tool reads your source, writes patches and can run your package scripts. That deserves more than a promise, so every guarantee has a test behind it:

The adversarial suite is written deliberately against the implementation: symlink escapes, stale caches, crash-safe journal manipulation, MCP boundary abuse.

Windows: the two symlink tests need Developer Mode. Without it they are skipped with a stated reason rather than failed — but the symlink protections are then unverified on that machine. Enable at Settings → System → For developers → Developer Mode.

Development

npm run typecheck
npm run lint
npm test                                   # 111 tests
node smoke_test.mjs                        # all five tools, live
node benchmark_runs/setup_worktrees.mjs    # prepare benchmark worktrees
CAPSULE_WORKTREE_BASE="<printed path>" npm run benchmark:retrieval

CI runs the same gates on Linux, macOS and Windows across Node 20, 22 and 24, with action versions pinned to immutable commit SHAs.

Windows joined the matrix on 2026-07-28. Until then only Linux and macOS ran, and three Windows-only defects had gone unnoticed: validate_delta never worked at all, the benchmark runner reported every command as "not found", and four tests failed for environment reasons. A test that does not run on a platform is a test that does not exist there.

Retrieval quality

Measured against the SDK repository. Most recent independent run (2026-07-28, base cc4b416):

Symbol recall sits below its threshold, and the cause is not a retrieval regression: four expected symbols (signalProcessGroup, stopProcessGroup, trimHeaderOws, serializeProtocolDocument) no longer exist upstream. The files are still there; the symbols were renamed.

An earlier run reported 100% for hit@1 and symbol recall, but those numbers cannot be reproduced — the commits they were pinned to were never recorded anywhere. That is why the oracle now writes baseCommit and measuredAt into every result. Details in benchmark_runs/RETRIEVAL-QUALITY-2026-07-28.md.

Nature.co ecosystem

Urðr remembers across sessions. Verðandi decides what matters right now. They stay separate on purpose: Verðandi keeps no session history and stores no large code fragments.

Architecture notes and per-agent commands live in UNIVERSAL.md and integrations/.

License

MIT — see LICENSE.