> 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/getting-started/readme.md).

# Overview

Codna understands a repository before it acts. It maps the code for about zero model tokens, then fixes, reviews and secures from the evidence. Runs on your machine or your cloud.

<figure><img src="https://2818771022-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuFbRKjfy5RJalcukhbG%2Fuploads%2Fgit-blob-43a6669e66380045a69ba3f79423f1ad4a62e02b%2Fcodna-hero.png?alt=media" alt="Codna"><figcaption></figcaption></figure>

Agents read your code. Codna understands it.

Codna maps your repository deterministically before it spends a model token. It hands the agent the evidence for this issue, not the whole tree, and reports the bundle size on every run. Point it at a local checkout or a git URL.

{% hint style="info" %}
New to Codna? Start with the [Quickstart](/getting-started/quickstart.md): install, add a model key, triage a repository, and open your first fix PR.
{% endhint %}

## Start here

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Quickstart</strong></td><td>Install, add a key, triage, and open a fix PR.</td><td><a href="/getting-started/quickstart.md">Quickstart</a></td></tr><tr><td><strong>Installation</strong></td><td>One pip command. No Node, Bun, Docker, or engine.</td><td><a href="/getting-started/installation.md">Installation</a></td></tr><tr><td><strong>CLI Reference</strong></td><td>Every command, argument, and flag.</td><td><a href="/reference/cli.md">CLI Reference</a></td></tr></tbody></table>

## Choose an outcome

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Fix a failing test</strong></td><td><code>codna fix</code> finds the root cause and opens a pull request you review.</td><td><a href="/getting-started/quickstart.md">Quickstart</a></td></tr><tr><td><strong>Review every pull request</strong></td><td><code>codna review</code> posts findings with severity, category and confidence, and approves a clean diff.</td><td><a href="/guides/review.md">codna review</a></td></tr><tr><td><strong>Prove a scanner finding</strong></td><td><code>codna secure</code> reads SARIF and proves which findings are reachable, for zero model tokens.</td><td><a href="/guides/security-autofix.md">Security Autofix</a></td></tr></tbody></table>

## Connect Codna

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>GitHub App</strong></td><td>Reviews pull requests when they open, answers <code>@codna review</code>, and opens fixes on request.</td><td><a href="/guides/github-app.md">GitHub App</a></td></tr><tr><td><strong>GitHub Action</strong></td><td><code>thyn-ai/codna-action@v1</code>: fix, review or secure from your own CI.</td><td><a href="/guides/github-action.md">GitHub Action</a></td></tr><tr><td><strong>MCP Server</strong></td><td>Five tools for Cursor, Claude Desktop, or your own agent.</td><td><a href="/guides/mcp.md">MCP Server</a></td></tr></tbody></table>

## Understand and explore

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>How It Works</strong></td><td>Snapshots, evidence bundles, blast radius, and the reduction ratio.</td><td><a href="/concepts/concepts.md">How It Works</a></td></tr><tr><td><strong>Privacy and data</strong></td><td>What leaves your machine, and what never does.</td><td><a href="/concepts/privacy.md">Privacy and data</a></td></tr><tr><td><strong>Configuration</strong></td><td>Environment variables and the <code>codna.yaml</code> file.</td><td><a href="/reference/configuration.md">Configuration</a></td></tr><tr><td><strong>Troubleshooting</strong></td><td>Every message and its one-line fix.</td><td><a href="/reference/troubleshooting.md">Troubleshooting</a></td></tr></tbody></table>

## What Codna does

You run one command, `codna`. Everything it needs ships inside the package. There is no server to start.

| Capability     | Command                                     | What it does                                                                                                                                                                                            | Model tokens  |
| -------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| Understand     | `codna triage`                              | Maps the repository and locates the code relevant to an issue. Deterministic.                                                                                                                           | 0             |
| Fix            | `codna fix`                                 | Finds the root cause and plans a patch. With `--apply` it writes a local branch; with `--open-pr` it opens a pull request. Every fix reports root cause, impacted symbols, confidence and blast radius. | On the patch  |
| Review         | `codna review`                              | Reviews a pull request read-only. Posts findings with severity, category and confidence. Approves a clean diff.                                                                                         | On the review |
| Secure         | `codna secure`                              | Reads SARIF from CodeQL, Semgrep, Snyk or Trivy and proves which findings are reachable.                                                                                                                | 0 to classify |
| Test selection | `codna impact`                              | Prints the tests a diff can affect. Offline.                                                                                                                                                            | 0             |
| Code memory    | `codna_recall` (MCP), `codna memory export` | On-device recall of the symbols relevant to a query.                                                                                                                                                    | 0             |
| Report         | `codna report`                              | Files a bug, request or question to [thyn-ai/feedback](https://github.com/thyn-ai/feedback).                                                                                                            | 0             |

The [GitHub App](/guides/github-app.md) and the [GitHub Action](/guides/github-action.md) run the same `codna` commands you run on your machine. A review posted by the App, by the Action, or by `codna review --post` reads the same way.

## Install

```bash
pip install codna
```

{% hint style="success" %}
No Node, Bun, Docker, or engine to install or start. Python 3.12 to 3.13 on macOS or Linux, with `git` on your `PATH`.
{% endhint %}

For pipx, uv, optional extras and offline use, see [Installation](/getting-started/installation.md). For keys and model selection, see [Models & BYOK](/concepts/models-and-byok.md).

## A first look

Point Codna at a directory to understand it. Triage spends no model tokens.

```bash
codna triage .
```

The values below show the format. Codna prints the measured values for your repository.

```
codna: understanding . …

✓ codna understood 412 files in 1.8s
  suspect files : src/checkout/total.py, src/checkout/cart.py
  context        : 1,840,000 → 9,400 tokens  (196× smaller for the agent)
```

Then fix a bug. Without `--apply` or `--open-pr`, `fix` reports its analysis and a patch reference and changes nothing.

```bash
codna fix . --issue "tests/test_checkout.py::test_total returns the pre-tax amount"
```

```
codna: fixing . …

✓ codna analyzed .
  root cause   : total() sums line items but never applies the tax_rate field
  symbol       : checkout.total.compute_total  (blast radius: 3)
  confidence   : 91%
  context      : 1,840,000 → 9,400 tokens  (196× 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)
```

Next: the [Quickstart](/getting-started/quickstart.md) walks install, triage, fix and PR end to end. The [CLI Reference](/reference/cli.md) documents every command.

## Community

Questions or feedback? File them with `codna report`, or join us on [Discord](https://discord.gg/w8NDsph9an). Security reports go to <security@codna.ai> and are acknowledged within two business days.


---

# 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/getting-started/readme.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.