> 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

<figure><img src="/files/SZ28IICMkCp8Xbh7kXIE" alt="Codna"><figcaption></figcaption></figure>

Codna is a command-line coding agent that maps your entire repository deterministically — for roughly zero LLM tokens — before it spends a token acting. Use it to understand an unfamiliar codebase, fix a failing test, or prove and remediate scanner findings, on a local checkout or a git URL, across 250 languages.

Other agents read your code one file at a time inside the model, burning tokens just to find where to act. Codna understands the repository first: a deterministic engine builds a dependency and blast-radius graph, then hands the agent a tight, issue-specific evidence bundle instead of the whole repo. Codna reports the bundle size on every run.

{% hint style="info" %}
New to Codna? Start with the [Quickstart](/getting-started/quickstart.md) — install, authenticate, and open your first fix PR in minutes.
{% 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, authenticate, and open your first fix PR.</td><td><a href="/pages/3ns1fuyAWbqtjiuEoeev">/pages/3ns1fuyAWbqtjiuEoeev</a></td></tr><tr><td><strong>Installation</strong></td><td>One pip command — no Node, Bun, Docker, or engine.</td><td><a href="/pages/EDfybAPmHhBDEsLseK1c">/pages/EDfybAPmHhBDEsLseK1c</a></td></tr><tr><td><strong>CLI Reference</strong></td><td>Every command, argument, and flag.</td><td><a href="/pages/0J2cLigcemMkzHZAo3sO">/pages/0J2cLigcemMkzHZAo3sO</a></td></tr><tr><td><strong>Codna Review</strong></td><td>Review every PR with high-confidence findings; fix each with <code>@codna fix</code>.</td><td><a href="/pages/LTdffMUbE5fOu21F6vtx">/pages/LTdffMUbE5fOu21F6vtx</a></td></tr><tr><td><strong>Security Autofix</strong></td><td>Prove scanner findings reachable and open one proven-safe fix per PR.</td><td><a href="/pages/X6XAuSHNkdWWSEb05lKs">/pages/X6XAuSHNkdWWSEb05lKs</a></td></tr><tr><td><strong>GitHub App</strong></td><td>The hosted bot that reviews PRs and opens verified fixes automatically.</td><td><a href="/pages/Kxw2qpud1EmsvKkLJtiQ">/pages/Kxw2qpud1EmsvKkLJtiQ</a></td></tr></tbody></table>

## Concepts and configuration

<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="/pages/BcyebIwMAgH27WETofBr">/pages/BcyebIwMAgH27WETofBr</a></td></tr><tr><td><strong>Models &#x26; BYOK</strong></td><td>The engine key vs. your own provider keys, and how to pin a model.</td><td><a href="/pages/e9RhUA1WEkuAT5PjUSAU">/pages/e9RhUA1WEkuAT5PjUSAU</a></td></tr><tr><td><strong>Configuration</strong></td><td>Every environment variable and the <code>codna.yaml</code> file.</td><td><a href="/pages/F9WliGfQ5ZeNYZbp8wFZ">/pages/F9WliGfQ5ZeNYZbp8wFZ</a></td></tr><tr><td><strong>MCP Server</strong></td><td>Give Cursor or Claude Desktop an agent that knows your codebase.</td><td><a href="/pages/EaMJtUY6WaMmNVhc8dKF">/pages/EaMJtUY6WaMmNVhc8dKF</a></td></tr><tr><td><strong>GitHub Action</strong></td><td>Open a fix PR automatically when CI fails.</td><td><a href="/pages/rRrfFy3uxrQbrSeOmpSD">/pages/rRrfFy3uxrQbrSeOmpSD</a></td></tr><tr><td><strong>Troubleshooting</strong></td><td>Every error message and its one-line fix.</td><td><a href="/pages/pKodemFOP7QR2Dw117qq">/pages/pKodemFOP7QR2Dw117qq</a></td></tr></tbody></table>

## What Codna does

You only run the `codna` CLI. On a local install it calls the bundled Algenta repository-intelligence SDK in-process and keeps its intermediate state in local files. Telys ships in the package. The agent-core sidecar starts only when verified planning needs a model. There's no engine server to start or configure.

| Capability    | Command                   | What it does                                                                                                                                           | LLM tokens               |
| ------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
| Triage        | `codna triage`            | Understand a repo and locate the relevant code. Deterministic graph build, no agent.                                                                   | \~0                      |
| Fix           | `codna fix`               | Find and fix a bug, then optionally apply a local branch or open a pull request — with a patch, root cause, confidence, and simulated regression risk. | Spent only on the patch  |
| Review        | `codna review`            | Review a PR read-only, post high-confidence inline findings, and open a verified fix on `@codna fix`.                                                  | Spent only on the review |
| Secure        | `codna secure`            | Ingest scanner findings (SARIF), prove which are reachable, then optionally remediate the eligible ones — one verified finding per PR.                 | \~0 to classify          |
| MCP server    | `codna mcp`               | Expose Codna to Cursor or Claude Desktop.                                                                                                              | —                        |
| GitHub Action | `thyn-ai/codna-action@v1` | Open a fix PR automatically when CI fails.                                                                                                             | —                        |

## Install

```bash
pip install codna
```

{% hint style="success" %}
The wheel is fully self-contained — the repository-intelligence SDK, the Telys memory runtime, and a compiled agent-core sidecar all ship inside it. `codna fix` needs **no Node, Bun, Docker, or engine**.
{% 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 .
```

```
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 a patch reference and changes nothing.

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

```
codna: fixing . …

✓ codna fixed . in 34s
  root cause   : total() sums line items but never applies the tax_rate field
  symbol       : checkout.total.compute_total  (blast radius: 3)
  confidence   : 91%  ·  regression risk: 4%
  context      : 1,840,000 → 9,400 tokens  (196× smaller)
  agent        : repository.verified_agentic_v1 via codna  ·  cost: $0.021
  patch        : ref:patch/9f2c1a   (--apply for a local branch · --open-pr to open a PR)
```

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

## Architecture

Codna is a fast agent head over Algenta's deterministic repository-intelligence and risk-simulation layer. The local path runs entirely on your machine — nothing to install, host, or start. See [How It Works](/concepts/concepts.md) for the full model.

## Community

Questions or feedback? Join us on [Discord](https://discord.gg/w8NDsph9an).


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.codna.ai/getting-started/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.