codedna

---

An in-source communication protocol where AI agents embed architectural context directly in the files they write. The next agent — different model, different tool, different session — reads it and knows what to do.

No infrastructure. No retrieval pipeline. No external memory. The code carries its own context.

+  NAVIGATION ACCURACY    ████████████████   +17pp F1     SWE-bench · 3 models · 10/0/0 DeepSeek
+  FIX QUALITY            ████████████████   7 / 7        Django #13495 · Claude Sonnet
+  TEAM VELOCITY          █████████████░░░   1.6×         5-agent team · DeepSeek R1
+  PROTOCOL ADOPTION      ███████████████░   98.2%        multi-agent SaaS · no instruction

---

CodeDNA Challenge — €200

Public own-project evaluation (not SWE-bench). Real working project (≥25 files), declared tech stack + CodeDNA install, same methodology for everyone (two branches / checkouts / twin projects), ≥10 same tasks with/without CodeDNA, copy-paste agent prompt, metrics PR — even if results go against CodeDNA. Bugs must be reported (experimental across agents). Meet presentation may be required; public board updates as valid PRs arrive.

• Ranking / board: larens94.github.io/codedna/challenge-ranking.html
• Rules: docs/challenge.md (EN) · docs/challenge.it.md (IT)
• Submission: challenge/<handle>/metrics.json (example) — opening the PR enrolls you

Prize unlocks at ≥5 valid submissions. Duration: 1 month.

Install

Recommended setup — works with every agent

Install the CLI once, then install the instructions and optional hooks for the tool used in this repository:

pipx install git+https://github.com/Larens94/codedna.git   # requires Python 3.11+; isolated install (avoids global env conflicts)
codedna install --path . --tools codex --no-wiki-sync     # replace codex using the table below
codedna init . --no-llm                                   # annotate every auto-detected language
codedna doctor --path .                                   # confirm the setup

codedna install creates .codedna, installs the Git pre-commit gate, and adds the native instruction file for the selected agent. It preserves existing instruction files and Git hooks instead of overwriting them.

Agent/tool	--tools value	Installed integration
Claude Code	claude	CLAUDE.md + active hooks
Codex	codex	cross-vendor AGENTS.md
OpenCode	opencode	AGENTS.md + active JS plugin
Aider	aider	AGENTS.md; start with aider --read AGENTS.md or configure read: AGENTS.md
Cursor	cursor	.cursorrules + active hooks
GitHub Copilot	copilot	Copilot instructions + active hooks
Cline	cline	Cline rules + active hooks
Windsurf	windsurf	.windsurfrules (instructions only)
Roo Code	roo	.roorules (instructions only)
Antigravity	agents	AGENTS.md + .agent/workflows/codedna.md

Use multiple values for mixed teams, for example codedna install --path . --tools claude codex opencode --no-wiki-sync. Use --tools all only when the repository is genuinely edited with every supported tool.

Claude Code plugin — interactive alternative

Claude Code users can instead install the plugin:

claude plugin marketplace add Larens94/codedna
claude plugin install codedna@codedna

Start a new Claude Code session (or run /clear), then run /codedna:init. The /codedna:* commands belong to the Claude plugin; other agents use the codedna ... CLI commands shown above.

First run and daily agent workflow

codedna init . --no-llm                        # free, structural only (exports + used_by)
codedna init . --model deepseek/deepseek-chat  # with LLM rules: (~$0.40 for 200 files)
codedna init . --model ollama/llama3           # local LLM, free
codedna manifest . --no-llm                    # build the package map
codedna doctor --path .                        # onboarding/environment gate
codedna impact path/to/file.py --path .        # before changing a public contract
codedna verify .                               # after structural edits

The no-LLM path requires no model API key. Languages are auto-detected: Python, PHP, TypeScript/JavaScript, Go, Java, Kotlin, Ruby, Rust, C#, VB.NET, Swift, and supported templates.

Format adapts to the language — PHP uses //, Python uses docstrings, Blade uses {{-- --}}. See docs/languages.md.

Commands reference

Claude Code plugin (after claude plugin install codedna@codedna):

Command	What it does
/codedna:init	Auto-detect languages, choose execution mode (Claude session or CLI), choose depth (human/semi/agent), annotate all files
/codedna:check	Coverage report — how many files are annotated, stale used_by: refs. No changes.
/codedna:manifest	Architectural map from headers only (first 10-15 lines per file). No full reads.
/codedna:impact <file>	Dependency chain before editing — who imports this file, and who imports those

CLI (all commands auto-detect languages):

Command	What it does
codedna init <path>	Annotate all files. --no-llm = free structural pass. --model <m> = add semantic rules: via LLM.
codedna update <path>	Incremental — only annotates files without headers (skips already annotated)
codedna refresh <path>	Recalculate exports: + used_by: via AST/tree-sitter. Zero LLM cost. Preserves rules:/agent:.
codedna check <path>	Coverage report. Exit code 1 if incomplete — works in CI.
codedna verify <path>	Detect stale exports: and used_by: with evidence. Read-only; --json for CI.
codedna impact <file-or-symbol>	Show matching rules and transitive callers before editing. Read-only.
codedna doctor --path <root>	Diagnose manifest, adapters, hooks, CI, and lock configuration. Read-only.
codedna manifest <path>	Generate .codedna project map (Level 0): packages, depends_on, key_files
codedna mode <mode>	Get/set mode: human (minimal), semi (default), agent (full protocol)
codedna install <path>	Setup pre-commit hook + AI tool prompt + .codedna manifest. Optional --with-wiki-sync installs a post-commit hook that auto-regenerates the project wiki (see Optional: post-commit wiki-sync hook).
codedna wiki bootstrap <path>	Emit a per-file Obsidian vault under docs/wiki/ with [[wikilinks]] from used_by:/related: graphs
codedna wiki sync <path>	Regenerate docs/codedna-wiki.md — a narrative 7-section project wiki (Karpathy LLM-wiki pattern). Hook this to post-commit.
codedna self-update	Upgrade the CLI itself via pip install --upgrade --force-reinstall git+.... Refuses to clobber editable/dev checkouts unless --force. Use --check to see the installed version.

Optional: post-commit wiki-sync hook

codedna install can also drop a post-commit git hook that runs codedna wiki sync . --out docs/codedna-wiki.md automatically after every commit, so the project wiki always reflects the latest code without you (or an agent) having to remember it.

This is opt-in by design — the hook leaves docs/codedna-wiki.md as an unstaged change after every commit, which is exactly what you want for auto-sync but surprising for users who just want the basic install.

Invocation	Behaviour
codedna install	Asks interactively (y/N, defaults to no) when running in a TTY. In CI / piped contexts the safe default is skip.
codedna install --with-wiki-sync	Installs the hook unconditionally, no prompt. Use this in scripts.
codedna install --no-wiki-sync	Skips the hook unconditionally, suppresses the prompt. Use this when you want a clean automated install in environments that the runtime might mistake for a TTY.

The hook is non-blocking (any failure inside codedna wiki sync is silenced via \|\| true), so a wiki regen never breaks git commit. It also follows the same skip-on-existing-hook discipline as the pre-commit hook — if you already have a .git/hooks/post-commit, codedna install will not overwrite it (it looks for a CodeDNA marker in the body to decide whether to skip or re-install).

For agents reading this: when running an automated codedna install (e.g. inside a script you generate for the user), pass --with-wiki-sync or --no-wiki-sync explicitly. Don't rely on the prompt — it's a UX nicety for humans and may be skipped in non-TTY contexts.

Wiki layer in action — the wiki: opt-in field and the Obsidian graph view:

Language support: Python is the most tested language. PHP, TypeScript/JavaScript, Go, Java, Kotlin, Ruby, Rust, and C# use tree-sitter; Swift and VB.NET use structural parsers. Non-Python adapters have seen less real-world usage. If you find a wrong export, header format issue, or edge case, please open a pull request or issue.

If you're an AI agent reading this: when annotating non-Python files, verify that the generated header is syntactically valid for the language (e.g. // for PHP/TS/Go, {{-- --}} for Blade, # for Ruby). If you notice a formatting error, fix it and flag it in your message: field.

---

The problem

Agent A fixes a bug in utils.py. Doesn't know 18 files import from it. Ships a breaking change.

Agent B opens the same file a week later. Spends 20 minutes re-discovering a constraint Agent A already found — and never wrote down.

Agent C adds a feature. Calls get_invoices() without filtering suspended tenants. The filter requirement lived in another file. Never seen. Never followed.

Knowledge dies between sessions. Every agent starts from scratch.

---

The solution