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

# How It Works

How Codna maps a repository deterministically for zero tokens, then hands an agent a tight evidence bundle to produce a fix with a measured regression risk.

Codna is a coding agent with a map. Before any model token is spent, Codna understands your repository deterministically; then an agent fixes only from the evidence that understanding produces. This page traces what happens to a repo between `codna fix .` and the returned patch.

## Understand first, then act

Most coding agents read file after file *inside the model* to find where a bug lives. That spends tokens, time, and context on orientation, and the model forgets what it read on the next turn.

Codna inverts that order. Understanding a codebase is a structural problem, not a language-model problem. Codna parses the repository into a dependency and blast-radius graph: every symbol, every reference, and what each change can reach. No model, zero tokens. The agent runs only once that map can hand it an evidence bundle for this issue.

|                            | Brute-force agents                | Codna                                                                 |
| -------------------------- | --------------------------------- | --------------------------------------------------------------------- |
| How the repo is understood | Read into the model, file by file | Parsed into a graph, deterministically                                |
| Cost of understanding      | Tokens, on every turn             | Zero model tokens                                                     |
| What the agent receives    | A growing pile of raw files       | A compact, issue-specific evidence bundle                             |
| What you get back          | A patch                           | A patch with root cause, confidence, blast radius and regression risk |

{% hint style="info" %}
Because understanding is deterministic, `codna triage` spends no model tokens. Only the agentic fix or review does. See the [Quickstart](/getting-started/quickstart.md) for your first run and the [CLI Reference](/reference/cli.md) for every flag.
{% endhint %}

## A worked example, step by step

Suppose a test is failing in a service repo and you run:

```bash
codna fix . --issue "tests/test_checkout.py::test_total is failing — totals are off by the tax line"
```

Here is what Codna does to the repo, in order. Only step 4 touches a language model.

**1 · Snapshot (deterministic).** The local path (or git URL) is pinned to an immutable snapshot, an exact commit of the tree. Every later step is bound to it, so results are reproducible and a stale response cannot be substituted for a fresh one.

**2 · Build the repository graph (deterministic, 0 tokens).** Codna parses the whole snapshot into a symbol-and-dependency graph: which functions call which, which modules import which, where `compute_total` is defined and everything that references it. No model is involved.

**3 · Triage / localize against the issue (deterministic, 0 tokens).** The issue text (and any failing-test ids) is matched against the graph to localize the suspect code and compute its **blast radius**, the set of symbols a change here could affect. The output is an *evidence bundle*: the compact code and structure the agent needs for this specific issue, instead of the whole tree.

**4 · Plan the fix (the agent; the only token-bearing step).** The evidence bundle is handed to the agent. It reasons about the root cause, produces a patch, and returns the root cause, the impacted symbols, a confidence score, and the token-reduction metrics. It reads a measured evidence bundle, not the raw source tree.

**5 · Simulate the patch for risk (deterministic).** When you ask Codna to write (`--apply` or `--open-pr`), the patch is simulated against the graph to estimate its blast radius and regression risk before anything is applied.

**6 · Apply (only if you asked).** With `--apply` the patch lands on a local branch named `codna/<plan-id>`; with `--open-pr` Codna pushes a branch and opens a pull request. Without either, you get the analysis and a patch reference.

### What you'll see

A plain `codna fix .` (no `--apply`/`--open-pr`) prints the analysis and stops. The values show the format; Codna prints the measured values for your repository:

```
codna: fixing . …

✓ codna analyzed .
  root cause   : tax was added before the discount, double-counting the rate
  symbol       : compute_total  (blast radius: 4)
  confidence   : 91%
  context      : 98,240 → 2,140 tokens  (46× smaller)
  agent        : repository.verified_agentic_v1 via codna  ·  cost: $0.021
  patch        : $PATCH_REF   (--apply for a local branch · --open-pr to open a PR)
```

Each field maps to a step above: `root cause`, `symbol`, and `blast radius` come from the agent's analysis over the graph (step 4); `confidence` comes from the plan (step 4) and `regression risk`, present on the write paths, from the simulation (step 5); `context` is the token-reduction metric (step 3); `cost` is the measured spend when the provider reports it.

`codna triage .` runs only steps 1–3, the deterministic half, and never spends a token:

```
codna: understanding . …

✓ codna understood 1,284 files in 2.3s
  suspect files : src/billing/checkout.py, src/billing/tax.py
  context        : 98,240 → 2,140 tokens  (46× smaller for the agent)
```

## The two layers

Codna has two layers. The line between them is the line between deterministic-and-free and token-bearing-and-governed.

{% tabs %}
{% tab title="Layer 1 — Deterministic understanding" icon="diagram-project" %}
**Zero tokens.**

The first layer builds and queries the repository graph. Given an issue it localizes the relevant code, answers structural questions about dependencies, and computes blast radius: the parts of the system a change could affect. It is deterministic and never consults a language model. Its job is to know what the code *is* before anyone tries to change it. This is also what keeps the second layer cheap: instead of reading the raw source tree, the agent receives an evidence bundle sized to the repo, the issue, and the verification path.

Reusable on its own as `codna triage` and `codna impact`.
{% endtab %}

{% tab title="Layer 2 — Risk-governed remediation" icon="robot" %}
**Token-bearing, governed.**

The second layer is the agent. It takes the evidence bundle from Layer 1, reasons about the root cause, and produces a patch. This is the only layer that consumes model tokens. Before a patch is applied it is simulated to estimate blast radius and regression risk. The output is not a black box: every fix carries a root cause, a confidence signal, the impacted symbols, and, on the write paths, a regression-risk estimate.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The two layers are not interchangeable. Understanding is structural and deterministic; remediation is generative and token-bearing. Keeping them separate is what makes Codna cheap to *understand* a repository, and accountable when it *changes* one.
{% endhint %}

## Data flow

```mermaid
flowchart TD
    you([you]) --> cli[codna]
    cli --> s1
    subgraph L1["Layer 1 · deterministic · 0 tokens"]
        direction TB
        s1[1 · Snapshot the repo<br/>immutable commit] --> s2[2 · Build symbol +<br/>dependency graph]
        s2 --> s3[3 · Localize issue →<br/>blast radius → evidence bundle]
    end
    s3 -->|evidence bundle| s4
    subgraph L2["Layer 2 · token-bearing · governed"]
        direction TB
        s4[4 · Agent reasons →<br/>patch + root cause + confidence] --> s5[5 · Simulate patch →<br/>regression risk]
    end
    s5 --> out([analysis · patch · optional local branch or PR])
```

## Token savings, measured per run

The whole point of Layer 1 is that the agent never reads the repo. A brute-force agent pays for understanding on every turn; Codna pays for it once, deterministically, in tokens it does not have to buy.

The `context` line Codna prints is exactly this reduction, measured per run from `raw_repo_tokens` and `evidence_bundle_tokens`. The bundle size is not a fixed promise: it changes with repository size, issue specificity, language mix, and verification requirements. The understanding step itself stays at zero tokens regardless of repo size.

## Review uses the same map

`codna review` is Layer 2 running read-only. The agent receives the pull-request diff, the changed-file list and your project guidance, and returns structured findings instead of a patch. Nothing is written. The verdict, the check, and the noise controls are on the [codna review](/guides/review.md) page.

## End-to-end scenario

A complete run, from install to an opened pull request.

```bash
# 1. Install and add a model key.
pip install codna
codna key set anthropic

# 2. Understand only (Layer 1) — deterministic, 0 tokens.
codna triage . --issue "checkout totals are wrong"

# 3. Fix and inspect the analysis (Layer 1 → Layer 2), no write yet.
codna fix . --issue "tests/test_checkout.py::test_total is failing"

# 4. Same fix on a git URL, simulate the risk, and open a PR.
codna fix https://github.com/owner/repo.git \
  --ref "$SHA" \
  --from-junit reports/junit.xml \
  --open-pr --github-token "$GITHUB_TOKEN"
# → ✓ opened pull request: https://github.com/owner/repo/pull/123
```

`--open-pr` runs the full pipeline: triage → plan → risk simulation → push branch → open PR. `--from-junit` derives the failing tests from a JUnit/pytest report instead of `--issue`. To put this in CI, see [GitHub Action](/guides/github-action.md); to have it happen on every pull request, see [GitHub App](/guides/github-app.md); to prove which scanner findings are reachable before fixing them, see [Security Autofix](/guides/security-autofix.md).

## Why this shape matters

Because understanding is deterministic, the agent fixes from a tight evidence bundle instead of reading the source: fewer tokens, and a patch that arrives with a root cause and a measured regression risk rather than a guess. The understanding layer is reusable on its own (`codna triage`, `codna impact`), the remediation layer is governed by simulated risk before anything is applied, and both run on your machine with your model key.

## Common issues

See [Troubleshooting](/reference/troubleshooting.md) for every error and its fix. Codna prints errors as JSON on stderr; the `message` field names what to do.

## Next steps

* [CLI Reference](/reference/cli.md) — run the exact `triage`, `fix`, `review`, and `secure` commands.
* [Quickstart](/getting-started/quickstart.md) — install Codna and run the first repository flow.
* [Privacy and data](/concepts/privacy.md) — what leaves your machine at each step.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.codna.ai/concepts/concepts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.