> 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/installation.md).

# Installation

Codna installs as a single Python package. `pip install codna` gives you the full agent: the repository-intelligence runtime, the on-device Telys memory kernel, and the compiled local agent runtime all ship inside the wheel.

{% hint style="success" %}
No Node, Bun, Docker, or engine to install or start. After `pip install codna`, `codna fix` works with nothing else on the machine.
{% endhint %}

## Requirements

* Python 3.10–3.13.
* macOS, Linux, or Windows. Codna ships platform-specific wheels; `pip` selects the right one.
* `git` on your `PATH`.

## Install

{% tabs %}
{% tab title="pip" %}

```bash
pip install codna
```

{% endtab %}

{% tab title="pipx" %}

```bash
pipx install codna
```

{% endtab %}

{% tab title="uv" %}

```bash
uv tool install codna
```

{% endtab %}
{% endtabs %}

This installs the `codna` command.

### Optional extras

Base `codna` already includes the memory kernel and the tree-sitter extractors. The extras add optional retrieval/rerank packages:

| Extra              | Command                                 | Adds                                                                                                                    |
| ------------------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `mcp`              | `pip install "codna[mcp]"`              | The `mcp` package for the `codna mcp` server (Cursor / Claude Desktop). Kept out of base so a plain install stays lean. |
| `memory`           | `pip install "codna[memory]"`           | `faiss-cpu` + `wordllama` (the default recall reranker).                                                                |
| `memory-rerank`    | `pip install "codna[memory-rerank]"`    | `wordllama` only, for `CODNA_MEMORY_RERANK=wordllama`.                                                                  |
| `memory-languages` | `pip install "codna[memory-languages]"` | Alias for the tree-sitter grammars already in base.                                                                     |

See [Code Memory](/concepts/memory.md) and [Language support](/concepts/languages.md).

## Verify

```bash
codna --version
codna status
```

`codna status` reports the runtime, the Telys kernel, and configured keys without spawning anything. For the full diagnostic, see [Operations](/reference/operations.md).

## Authenticate

Two credentials, two jobs (see [Models & BYOK](/concepts/models-and-byok.md)):

1. `codna login` — authorizes this device for on-device memory. Free for one device; works offline.
2. A model key — the LLM key the agent uses. Set your own with `codna key set <provider>`, or set `CODNA_API_KEY` for a managed engine key.

## Upgrade and uninstall

```bash
pip install --upgrade codna
pip uninstall codna
```

Per-repository memory lives in each repo's `.codna-memory/`; device state lives under `~/.codna/` and `~/.telys/`. Delete these independently.

## Offline use

Repository understanding, `codna triage`, and `codna_recall` run fully offline. The only outbound dependency is the LLM call in `codna fix`/`review`, which reaches your model provider.

## Next steps

* [Quickstart](/getting-started/quickstart.md) — open your first fix PR.
* [Models & BYOK](/concepts/models-and-byok.md) — set up a model key.
* [Operations](/reference/operations.md) — verify and manage the local runtime.


---

# 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/installation.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.