Docs

How CoDNA works, and why it works that way. These pages come from the project's own repository, so they change with the code.

Getting started

Connect your AI agentCoDNA is meant to be read through the agent you already talk to. Each person connects their own: the agent signs in as you, and searches, reads and writes exactly what you can, nothing more.
SkillsA skill tells an agent how your team does a task: how to write a proposal for a customer, how to answer a question about refunds, what goes in a weekly report. In CoDNA a skill is an ordinary page in the wiki's skills…
AgentsAn agent your team runs for other people, such as a support bot, an onboarding guide or an assistant in a channel, can use CoDNA as what it knows. It is not anybody's assistant, so it does not sign in as a person. It is…

How it works

ArchitectureA company's knowledge is scattered across Slack threads, Google Docs, PDFs, and people's heads. Teams increasingly ask an AI agent instead of searching, but the agent has nowhere trustworthy to look — and if you give it…
PermissionsCoDNA's central constraint: an AI agent acting for a person must see exactly what that person can see. Not more. Every rule below exists to make that true on all three surfaces — the REST API, the MCP server, and search…
LinkingDocuments reference each other with ordinary inline markdown links. Those references form a graph, and the graph is what powers share suggestions, backlinks, and the "a document you link to just moved" flow.
Images and filesA page can hold images and PDFs. Each one belongs to that page and to nothing else: whoever can read the page can open its files, whoever can edit the page can add to it, and sharing the page shares them. There is no…
SearchTypesense holds a derived index. It is never written to directly and never read as truth — it can be dropped and rebuilt from Postgres at any time. What it must never do is show someone a document they cannot open.
IngestionIngestion gets existing material into CoDNA: uploads, pasted text, scraped pages, whole exports from another tool, recordings of meetings. Everything it produces lands in raw as markdown, with the original file kept…
TranscriptionCoDNA turns a recording into a transcript in raw. It does not transcribe anything itself. It hands the recording to a transcription service at CODNA_TRANSCRIBE_URL and writes the page from what the service answers.…
MeetingsPeople start an online meeting from their workspace, hold it as a video call, and find it in raw afterwards: the recording, and a transcript that names who said what. CoDNA runs no calls itself. A meetings service at…
AutomationsSharing everything tagged runbook with the ops team is a one-time action. Making it keep happening is a script. (Sharing a folder needs no script: a folder share stands, and shares what is put there later — see…
MCP serverCoDNA's reason for existing. An agent connects on behalf of a person and gets exactly that person's visibility — no more, and the same rules the web UI enforces.
ExportExport is not a backup format. It is the answer to "what happens if we stop using CoDNA?" — and the answer has to be a directory of markdown files that are useful on their own.
Data modelPostgres is the source of truth for everything. Typesense holds a derived index that can be dropped and rebuilt at any time (search.md). This document specifies every table, the state machines that govern them, and — at…

Reference

SettingsCoDNA is configured through the environment and nothing else: the one mechanism that works the same in a shell, a Compose file, a Kubernetes ConfigMap and a systemd unit. These are all of its settings. .env.example sets…
Command lineEvery command of codna, the one binary that runs CoDNA and everything around it, with each command's flags.
MCP toolsWhat an agent connected to CoDNA is offered: 39 tools, each as tools/list describes it to the model. How an agent connects, and what it is told when it does, are in MCP server. Every tool acts as the person the agent…

Decisions

Architecture decision recordsOne record per decision that would be expensive to reverse. Each states what was chosen, what was rejected, and what it costs — the rejected options matter as much as the choice, because the next person to question a…
0001 · Record architecture decisionsCoDNA is open source. People who did not attend the conversation will read the schema and ask why it is shaped this way — and a decision whose reasoning is lost gets re-litigated, or worse, reversed by someone who…
0002 · Single org per deploymentCoDNA could scope every table by organization and host many companies from one deployment, or treat one deployment as one company. This decision reaches every query and every permission check, so it cannot be deferred.
0003 · Go, shipped as a single static binaryThe first draft specified a TypeScript monorepo — defensible, since the MCP SDK, Typesense client, and web framework are all first-class there. On review, the deployment story decided it.
0004 · Three spaces: raw, wiki, outputA knowledge base that mixes an uploaded PDF, a curated onboarding page, and last quarter's generated report in one undifferentiated pile cannot answer "what do we actually know?" — and an agent searching it cannot tell…
0005 · Postgres is truth, Typesense is derivedCoDNA needs full-text search with typo tolerance and faceting, and it needs transactional writes with foreign keys and recursive graph traversal. No single engine is good at both.
0006 · Inline markdown links with relative .md hrefsDocuments reference each other, and those references form the graph that drives share suggestions and backlinks. The href format determines whether an export is useful, what a rename costs, and whether a person can…
0007 · QuickJS on wazero for user automationsUsers need continuous behaviour — "whenever a document is tagged runbook, share it with ops" — plus scheduled jobs. The scripts are written by AI agents on request and run inside CoDNA, on behalf of whoever owns them.…
0008 · Tombstone deletion with pending link decisionsDocuments link to each other. Deleting one breaks inbound links belonging to other people, who may not know the document existed and certainly did not agree to lose the reference.
0009 · Transactional outbox for all derived stateA document write must update Postgres, the Typesense index, the link graph, any matching automations, and possibly several notifications. Those cannot share a transaction, and the search index in particular must never…
0010 · CoDNA does not call an LLMCoDNA's pitch involves AI: uploads become a wiki, related documents get suggested, knowledge gets distilled. The question is where the model runs — inside CoDNA, or in the client connected to it.
0011 · OCI containers, Podman first, three deployment strategiesCoDNA is self-hosted software. How it is installed is a feature, not an afterthought — the people evaluating it are infrastructure engineers deciding whether it is worth their afternoon.
0012 · MCP authenticates via OAuth against your IdP; humans use passwords for nowCoDNA has two kinds of caller and they are not alike.
0013 · No administrators; management is a token, not a personCoDNA had two roles. A member saw what they created and what was shared with them or with a group they were in. An admin saw everything: the policy, the visibility queries, the search filter, automations and export each…
0014 · Standing folder sharesSharing was one document at a time, or a one-time expansion by tag. Continuous behaviour was deliberately left to automations: a standing rule that widens access was thought hard to reason about, while a script is…
0015 · Images and files belong to a pagePages could not show a picture. A screenshot of an error, a diagram of a deploy, a scanned form: each had to live somewhere else, behind a link that a reader with access to the page might not be able to open, and that…
0016 · An export is imported into raw, and a newer export adds versionsA new company's CoDNA starts empty, and what it already knows is in Notion, Confluence, an Obsidian vault or Google Drive. codna import reads a markdown tree, but only on the host, which a hosted customer cannot reach.…
0017 · Recordings become raw transcripts, through a transcription serviceA great deal of what a company knows is said in meetings and never written down. A recorded online meeting, or an in-person one recorded on someone's phone, is evidence like any document: it belongs in raw, and an agent…
0018 · Meetings are held through a meetings service and recorded one person to a track0017 let people bring a meeting into raw by recording it: uploading a file from another tool, or recording the room in the browser. Both hand the transcription service one track with everyone on it, and the service can…
0019 · Diagrams are Mermaid text, drawn by the web UIA knowledge base explains systems, and systems are explained with diagrams: how the parts connect, who calls whom, what state a thing moves through. CoDNA's own architecture was drawn outside CoDNA, because CoDNA could…
0020 · Anyone who can edit a page can share itUntil now only a document's creator could share it. A write grant let someone change a page, move it and restore it, but not show it to anyone else. The reason was provenance: the set of people who could see a page…
0021 · An agent is a member of an instance, and knows what is shared with itToday every agent connected to CoDNA acts for a person. Claude or ChatGPT signs in as someone and sees exactly what they see (0012). That serves someone working with their own assistant. It does not serve an agent a…
0022 · A skill is a page in the wiki's skills folder, and agents are told which they can readAn agent connected to CoDNA reads a page when it thinks to. Teams also want to tell it how to do things their way: how to write a proposal for a customer, how to answer a question about refunds, what a weekly report…