> For the complete documentation index, see [llms.txt](https://kerno.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kerno.gitbook.io/docs/core-concepts/codebase-indexing.md).

# Codebase Indexing

Understand how Kerno builds a deterministic index of your codebase, keeps it up to date, and why it matters for accurate validation.

Most code tools that use LLMs rely on vector embeddings, which find relevant code by similarity. That is useful but approximate, and it does not reflect how your code is actually wired together.

**Kerno indexes deterministically**. It resolves symbols and cross-references straight from your source, so every function call, import, and variable reference gets a precise location that is reproducible across runs. The same index drives entry point discovery and impact analysis.

Route discovery is not pattern matching on filenames. Kerno reads each framework's routing constructs directly, so a route registered in a nested router group or behind a decorator is found the same way an obvious one is. See [Supported Technologies](https://kerno.gitbook.io/docs/references/supported-technologies.md) for the frameworks covered.

When Kerno finds no entry points in an application, for example one built on a framework it does not cover, an AI agent reads the code to find them. When you ask Kerno to test a route it did not list, it searches your code for that route's handler.

By default, Kerno shares the index through your repository's git remote, `origin`. Once a commit is on `origin`, Kerno pushes the index it built for that commit there as hidden refs under `refs/index/`, and fetches the entries your teammates pushed, so each commit is indexed once for the whole team. An entry holds none of your source files. It does hold file paths, symbol names, signatures and doc comments, and anyone who can read the repository can fetch it.

In CI, Kerno fetches and pushes the index with the git credentials your checkout already uses, and pushes once more before it exits, so a CI job shares the index with your team too.

Relevant code excerpts are sent to LLM providers only when Kerno needs them to reason about a specific task. See [Security & Privacy](https://kerno.gitbook.io/docs/references/security-and-privacy.md).

```mermaid
   flowchart TD
       src["src/"]
       src --> routes["routes/"]
       src --> services["services/"]
       src --> models["models/"]

       routes --> userRouter["userRouter.ts"]
       services --> userService["userService.ts"]
       models --> userModel["userModel.ts"]

       userRouter --> createUser["POST /users"]
       userRouter --> getUser["GET /users/:id"]
       userService --> hashPassword["hashPassword()"]
       userService --> dbQuery["db.query()"]
       userModel --> emailField["email: string"]
       userModel --> idField["id: string"]

       classDef file stroke:#3b82f6,stroke-width:2px,fill:transparent
       classDef endpoint stroke:#f59e0b,stroke-width:2px,fill:transparent
       classDef symbol stroke:#10b981,stroke-width:2px,fill:transparent

       class userRouter,userService,userModel file
       class createUser,getUser endpoint
       class hashPassword,dbQuery,emailField,idField symbol
```

Directories, files, entry points, and the symbols inside them are all nodes in one graph. Kerno traverses it in either direction: outward from a function to the entry points that reach it, or inward from an entry point to everything it touches.

### What the graph gives you

* **Deterministic blast-radius detection.** When you change code, Kerno knows which entry points, tests, and dependencies are affected. It follows the call graph outward across your whole codebase, so a change to a shared helper surfaces every entry point downstream of it.
* **No hallucinated context.** When Kerno asks an LLM to plan a test or update a baseline, it sends real code references rather than similarity matches.
* **Re-indexing on change.** When Kerno syncs after a code change, it rebuilds its index for your current code, so the blast radius reflects what is on disk.

### What gets indexed

Kerno indexes the git-tracked source files in your project, including application code, configuration, and build files. Files that are not tracked by git (dependency directories, build outputs, anything in `.gitignore`) are skipped automatically.

A new file you just created is untracked until you stage or commit it, so stage or commit it before expecting Kerno to index and validate it.

In a monorepo, Kerno detects each application in the repository and indexes them into one graph that spans the whole repo.

### Index updates

Kerno indexes your codebase on first use. After that, your AI coding agent syncs the workspace after code changes, so Kerno always runs against the latest version of your code.

You can also trigger a sync yourself. Ask your coding agent to sync the workspace

{% code expandable="true" %}

```
Sync the Kerno workspace so it picks up my latest changes.
```

{% endcode %}

Kerno takes a fresh snapshot of your code and re-runs its analysis.

{% hint style="warning" %}
A sync stops every Kerno run in progress, including test generation and change reviews. Let running work finish before you sync.
{% endhint %}
