{
  "markdown": "<p align=\"center\">\n  <img src=\"./docs/logo.png\" width=\"120\" />\n</p>\n\n<h1 align=\"center\">CodeDNA</h1>\n\n<p align=\"center\">\n  <strong>The file is the channel. Every fragment carries the whole.</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"./SPEC.md\"><img src=\"https://img.shields.io/badge/protocol-v0.9-6366f1\" alt=\"Protocol\"></a>\n  <a href=\"https://doi.org/10.5281/zenodo.19158336\"><img src=\"https://img.shields.io/badge/DOI-zenodo.19158336-blue\" alt=\"DOI\"></a>\n  <a href=\"./LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"></a>\n  <a href=\"https://github.com/Larens94/codedna/actions/workflows/ci.yml\"><img src=\"https://github.com/Larens94/codedna/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"></a>\n  <a href=\"docs/languages.md\"><img src=\"https://img.shields.io/badge/languages-11-6366f1\" alt=\"Languages\"></a>\n  <a href=\"https://discord.gg/7Fs5J2ua\"><img src=\"https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white\" alt=\"Discord\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"#install\">Install</a> · \n  <a href=\"#the-problem\">Problem</a> · \n  <a href=\"#the-solution\">Solution</a> · \n  <a href=\"#evidence\">Evidence</a> · \n  <a href=\"#multi-language--go-ruby-php-and-more\">Multi-language</a> · \n  <a href=\"#how-it-works\">How it works</a> · \n  <a href=\"#docs\">Docs</a>\n</p>\n\n<p align=\"center\">\n  <strong>English</strong> · <a href=\"./README-it.md\">Italiano</a>\n</p>\n\n---\n\nAn 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.\n\nNo infrastructure. No retrieval pipeline. No external memory. The code carries its own context.\n\n```diff\n+  NAVIGATION ACCURACY    ████████████████   +17pp F1     SWE-bench · 3 models · 10/0/0 DeepSeek\n+  FIX QUALITY            ████████████████   7 / 7        Django #13495 · Claude Sonnet\n+  TEAM VELOCITY          █████████████░░░   1.6×         5-agent team · DeepSeek R1\n+  PROTOCOL ADOPTION      ███████████████░   98.2%        multi-agent SaaS · no instruction\n```\n\n---\n\n## CodeDNA Challenge — €200\n\nPublic **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](docs/challenge-agent-prompt.md), 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.\n\n- Ranking / board: [larens94.github.io/codedna/challenge-ranking.html](https://larens94.github.io/codedna/challenge-ranking.html)\n- Rules: [`docs/challenge.md`](docs/challenge.md) (EN) · [`docs/challenge.it.md`](docs/challenge.it.md) (IT)\n- Submission: `challenge/<handle>/metrics.json` ([example](challenge/metrics.example.json)) — **opening the PR enrolls you**\n\nPrize unlocks at **≥5 valid submissions**. Duration: **1 month**.\n\n\n## Install\n\n### Recommended setup — works with every agent\n\nInstall the CLI once, then install the instructions and optional hooks for the tool used in this repository:\n\n```bash\npipx install git+https://github.com/Larens94/codedna.git   # requires Python 3.11+; isolated install (avoids global env conflicts)\ncodedna install --path . --tools codex --no-wiki-sync     # replace codex using the table below\ncodedna init . --no-llm                                   # annotate every auto-detected language\ncodedna doctor --path .                                   # confirm the setup\n```\n\n`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.\n\n| Agent/tool | `--tools` value | Installed integration |\n|---|---|---|\n| **Claude Code** | `claude` | `CLAUDE.md` + active hooks |\n| **Codex** | `codex` | cross-vendor `AGENTS.md` |\n| **OpenCode** | `opencode` | `AGENTS.md` + active JS plugin |\n| **Aider** | `aider` | `AGENTS.md`; start with `aider --read AGENTS.md` or configure `read: AGENTS.md` |\n| **Cursor** | `cursor` | `.cursorrules` + active hooks |\n| **GitHub Copilot** | `copilot` | Copilot instructions + active hooks |\n| **Cline** | `cline` | Cline rules + active hooks |\n| **Windsurf** | `windsurf` | `.windsurfrules` (instructions only) |\n| **Roo Code** | `roo` | `.roorules` (instructions only) |\n| **Antigravity** | `agents` | `AGENTS.md` + `.agent/workflows/codedna.md` |\n\nUse 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.\n\n### Claude Code plugin — interactive alternative\n\nClaude Code users can instead install the plugin:\n\n```bash\nclaude plugin marketplace add Larens94/codedna\nclaude plugin install codedna@codedna\n```\n\nStart 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.\n\n### First run and daily agent workflow\n\n```bash\ncodedna init . --no-llm                        # free, structural only (exports + used_by)\ncodedna init . --model deepseek/deepseek-chat  # with LLM rules: (~$0.40 for 200 files)\ncodedna init . --model ollama/llama3           # local LLM, free\ncodedna manifest . --no-llm                    # build the package map\ncodedna doctor --path .                        # onboarding/environment gate\ncodedna impact path/to/file.py --path .        # before changing a public contract\ncodedna verify .                               # after structural edits\n```\n\nThe 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.\n> Format adapts to the language — PHP uses `//`, Python uses docstrings, Blade uses `{{-- --}}`. See [docs/languages.md](docs/languages.md).\n\n### Commands reference\n\n**Claude Code plugin** (after `claude plugin install codedna@codedna`):\n\n| Command | What it does |\n|---|---|\n| `/codedna:init` | Auto-detect languages, choose execution mode (Claude session or CLI), choose depth (human/semi/agent), annotate all files |\n| `/codedna:check` | Coverage report — how many files are annotated, stale `used_by:` refs. No changes. |\n| `/codedna:manifest` | Architectural map from headers only (first 10-15 lines per file). No full reads. |\n| `/codedna:impact <file>` | Dependency chain before editing — who imports this file, and who imports those |\n\n**CLI** (all commands auto-detect languages):\n\n| Command | What it does |\n|---|---|\n| `codedna init <path>` | Annotate all files. `--no-llm` = free structural pass. `--model <m>` = add semantic `rules:` via LLM. |\n| `codedna update <path>` | Incremental — only annotates files without headers (skips already annotated) |\n| `codedna refresh <path>` | Recalculate `exports:` + `used_by:` via AST/tree-sitter. Zero LLM cost. Preserves `rules:`/`agent:`. |\n| `codedna check <path>` | Coverage report. Exit code 1 if incomplete — works in CI. |\n| `codedna verify <path>` | Detect stale `exports:` and `used_by:` with evidence. Read-only; `--json` for CI. |\n| `codedna impact <file-or-symbol>` | Show matching rules and transitive callers before editing. Read-only. |\n| `codedna doctor --path <root>` | Diagnose manifest, adapters, hooks, CI, and lock configuration. Read-only. |\n| `codedna manifest <path>` | Generate `.codedna` project map (Level 0): packages, depends_on, key_files |\n| `codedna mode <mode>` | Get/set mode: `human` (minimal), `semi` (default), `agent` (full protocol) |\n| `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](#optional-post-commit-wiki-sync-hook)). |\n| `codedna wiki bootstrap <path>` | Emit a per-file [Obsidian](https://obsidian.md) vault under `docs/wiki/` with `[[wikilinks]]` from `used_by:`/`related:` graphs |\n| `codedna wiki sync <path>` | Regenerate `docs/codedna-wiki.md` — a narrative 7-section project wiki (Karpathy LLM-wiki pattern). Hook this to post-commit. |\n| `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. |\n\n### Optional: post-commit wiki-sync hook\n\n`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.\n\n**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.\n\n| Invocation | Behaviour |\n|---|---|\n| `codedna install` | Asks interactively (`y/N`, defaults to no) when running in a TTY. In CI / piped contexts the safe default is **skip**. |\n| `codedna install --with-wiki-sync` | Installs the hook unconditionally, no prompt. Use this in scripts. |\n| `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. |\n\nThe 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).\n\n> **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.\n\n**Wiki layer in action** — the `wiki:` opt-in field and the Obsidian graph view:\n\n<p align=\"center\">\n  <img src=\"./docs/codedna-wiki-flow-en.gif\" width=\"600\" alt=\"wiki: field — two paths\" />\n</p>\n\n<p align=\"center\">\n  <img src=\"./docs/obsidian.png\" width=\"720\" alt=\"Obsidian graph view of a real project annotated with CodeDNA\" />\n</p>\n\n> **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](https://github.com/Larens94/codedna/pulls) or [issue](https://github.com/Larens94/codedna/issues).\n>\n> **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.\n\n---\n\n## The problem\n\nAgent A fixes a bug in `utils.py`. Doesn't know 18 files import from it. Ships a breaking change.\n\nAgent B opens the same file a week later. Spends 20 minutes re-discovering a constraint Agent A already found — and never wrote down.\n\nAgent C adds a feature. Calls `get_invoices()` without filtering suspended tenants. The filter requirement lived in another file. Never seen. Never followed.\n\n**Knowledge dies between sessions.** Every agent starts from scratch.\n\n---\n\n## The solution\n\n<table>\n<tr>\n<td width=\"55%\">\n\n```python\n\"\"\"revenue.py — Monthly revenue aggregation.\n\nexports: monthly_revenue(year, month) -> dict\nused_by: api/reports.py → revenue_route\n         api/serializers.py → Schema [cascade]\nrelated: billing/currency.py — shares multi-currency\n         conversion logic (no import link)\nwiki:    docs/wiki/revenue.md\nrules:   get_invoices() returns ALL tenants\n         — MUST filter is_suspended() BEFORE sum\nagent:   claude-sonnet | 2026-03-10\n         message: \"rounding edge case in\n                  multi-currency — investigate\"\nagent:   gemini-2.5-pro | 2026-03-18\n         message: \"@prev: confirmed → promoted\n                  to rules:\"\n\"\"\"\n```\n\n</td>\n<td width=\"45%\">\n\n**One read. The agent knows:**\n\n**`used_by:`** — 2 files depend on me. One is `[cascade]` — must update if I change.\n\n**`related:`** — another file shares my currency logic but doesn't import me. Check it too.\n\n**`wiki:`** — opt-in pointer to a curated markdown with deeper context. If present, a prior agent decided this file deserves extended notes; read it before editing.\n\n**`rules:`** — upstream function returns all tenants. I must filter.\n\n**`message:`** — previous agent found a rounding bug. The one after confirmed it and promoted it to a rule.\n\nNo grep. No reading 18 files. No re-discovering constraints.\n\n</td>\n</tr>\n</table>\n\n---\n\n## Evidence\n\n> The tables below report historical experiments; raw run artifacts are not currently shipped in this checkout. See [the benchmark reproducibility note](docs/benchmark.md) before interpreting the figures as independently reproducible.\n\n### Agents find the right files faster\n\nSWE-bench, Django bugs, 3 runs per condition. Same prompt, same tools. Only difference: CodeDNA annotations.\n\n| Model | Without | With CodeDNA | Delta |\n|---|---|---|---|\n| Gemini 2.5 Flash (5 tasks) | 60% F1 | **72% F1** | **+13pp** (p=0.040) |\n| DeepSeek Chat (10 tasks, 3 runs) | 51% F1 | **68% F1** | **+17pp** (p=0.001, Wilcoxon · 10/0/0) |\n| Gemini 2.5 Pro (5 tasks) | 60% F1 | **69% F1** | **+9pp** |\n\n**Stability over luck.** On DeepSeek the advantage is not just higher mean — it's lower variance. On tasks 11808 and 13121, CodeDNA std across 3 runs is 0.00 (same result every time), while control std is 0.20–0.25 (the agent sometimes guesses right, sometimes not). All 10/10 tasks favor CodeDNA, with no inversions. The agent with annotations works by **structural understanding**, not serendipity.\n\n> 6 of the 10 DeepSeek tasks (13121, 15629, 16263, 11400, 11883, 11808) were run independently by [@fabioscialanga](https://github.com/fabioscialanga) and contributed via [PR #2](https://github.com/Larens94/codedna/pull/2). Independent replication on a separate machine with the same protocol.\n\n### Agents fix the right pattern\n\nDjango bug #13495. Same model (Claude Sonnet). One `Rules:` annotation said *\"timezone conversion must happen BEFORE datetime functions.\"* The control agent saw `time_trunc_sql` on the line below the bug — and didn't touch it. CodeDNA did.\n\n| | Without | With CodeDNA |\n|---|---|---|\n| Files matching official patch | 6 / 7 | **7 / 7** |\n| Failed edits | 5 | **0** |\n\n### Agents leave knowledge for each other\n\n5-agent team builds a SaaS webapp. 83 minutes, DeepSeek R1. Agents were shown the `message:` format but never instructed to use it as a backlog or risk tracker. **They did it on their own.**\n\n**53 notes across 54 files.** Three patterns emerged:\n\n```python\n# Backlog — \"I built this, here's what's still needed\"\nmessage: \"implement memory summarization for long conversations\"\n\n# Risk flag — \"This works but I couldn't verify this part\"\nmessage: \"verify that refresh token rotation prevents replay attacks\"\n\n# Architecture — \"Consider this for production\"\nmessage: \"ensure credit balance uses materialized view for performance\"\n```\n\nWithout these notes, the next agent opens `auth_service.py` and has no idea refresh tokens need verification. With them, **the codebase knows what it's missing**.\n\n| Experiment | Result |\n|---|---|\n| Multi-agent RPG (5 agents, DeepSeek Chat) | **1.6x faster**, playable game vs static scene |\n| Multi-agent SaaS (5 agents, DeepSeek R1) | **98.2% adoption**, lower complexity (2.1 vs 3.1) |\n| Fix quality (Claude Sonnet) | **7/7** patch files vs 6/7, zero failed edits |\n\n### Annotations as architectural contracts in multi-agent teams\n\nIn the SaaS experiment (5 agents, DeepSeek R1), something unexpected happened: the **Director agent** (ProductArchitect) used `used_by:` not just to document existing imports, but as **architectural contracts for files that didn't exist yet**.\n\n```python\n# Written by ProductArchitect BEFORE BackendEngineer ran\n\"\"\"models.py — Core database models.\n\nexports: Base, User, Agent, AgentRun, CreditAccount, Invoice\nused_by: session.py, seed.py, all API routers     ← these files don't exist yet\nrules:   all models must inherit from Base; use UUID for public IDs; timestamps in UTC\n\"\"\"\n```\n\nThe flow:\n\n```\n  ProductArchitect             BackendEngineer              DataEngineer\n  ─────────────────           ─────────────────           ─────────────────\n  creates models.py            reads models.py              reads credits.py\n  writes:                      sees:                        sees:\n    used_by: all API routers     \"I must build routers        \"operations must be\n    rules: use UUID, UTC          that consume this\"           atomic, SELECT FOR\n                                                               UPDATE\"\n  creates api/ stubs           builds full API routers\n  writes:                      respects UUID + UTC          builds billing/stripe\n    used_by: main.py            constraint from rules:       respects atomicity\n                                                             constraint\n       ↓ exits                      ↓ exits                      ↓ exits\n  ─────────────────────────────────────────────────────────────────────────\n  No direct communication. The code carried the contracts.\n```\n\nEach agent wrote what it built and what it expects. The next agent read those expectations and fulfilled them — without any orchestrator passing messages, without shared memory, without API calls between agents. **The code was the only communication channel.**\n\nThis pattern works with any number of agents. The more agents in the team, the more valuable the annotations become — each agent leaves a richer contract for the next one.\n\n```python\n# FrontendDesigner reads jwt.py (written by BackendEngineer)\n# Sees: rules: must use settings.SECRET_KEY; must validate token expiration\n# Sees: message: \"implement token blacklist for logout functionality\"\n# → Builds auth UI that respects the JWT contract\n# → Adds its own message: \"implement social OAuth2 providers (Google, GitHub)\"\n```\n\nIn the same experiment, the team **without CodeDNA** hit a critical failure: one agent started building with Flask, another switched to FastAPI mid-session. Both frameworks ended up in the codebase simultaneously — no annotation existed to say \"we're using FastAPI, not Flask.\" With CodeDNA, `rules: must register all routers before returning app` on `main.py` locked the architectural choice from the first agent onward.\n\n**This is the key insight for multi-agent software engineering:** CodeDNA annotations are not just documentation — they are a **coordination protocol**. No orchestrator needed. No shared memory. The code is the channel.\n\n### Agents find cross-cutting dependencies\n\nDjango bug #11532 (unicode domain crash). The fix spans 5 files across `mail/`, `validators.py`, `encoding.py`, `html.py` — no import chain connects them. They share IDNA/punycode logic independently.\n\n`used_by:` alone can't find them. But `related:` can:\n\n```python\n\"\"\"mail/utils.py — Email sending helper functions.\n\nexports: class CachedDnsName | DNS_NAME\nused_by: mail/message.py → DNS_NAME\nrelated: django/core/validators.py — shares IDNA/punycode domain encoding logic\n         django/utils/encoding.py — encoding utilities for non-ASCII domains\nrules:   get_fqdn() returns raw unicode hostname — callers must handle non-ASCII\n\"\"\"\n```\n\n| Condition | Files found | F1 |\n|---|---|---|\n| Control (no annotations) | 2 / 5 | 40% |\n| CodeDNA with `used_by:` only | 2 / 5 | 40% |\n| CodeDNA with `used_by:` + `related:` | **5 / 5** | **100%** |\n\n`related:` captures **semantic links** — files that share the same pattern without importing each other. `used_by:` answers *\"who imports me?\"*, `related:` answers *\"who does the same thing as me?\"*.\n\n<details>\n<summary>Navigation demo — real benchmark data</summary>\n\n![CodeDNA Navigation Demo](./docs/codedna_viz.gif)\n\n> Without CodeDNA: agent opens random files, misses 8/10 critical files.\n> With CodeDNA: follows `used_by:` chain, finds 6/10. Retry risk −52%.\n> [Interactive version](./docs/codedna_viz_3metaphors.html)\n\n</details>\n\n> [Full benchmark](docs/benchmark.md) · [Experiment details](docs/experiments.md) · [Agent test sessions](docs/agent-tests.md) · [Raw data](benchmark_agent/runs/)\n\n---\n\n## Multi-language — Go, Ruby, PHP, and more\n\nThe same command works on all supported languages. DeepSeek generates `rules:` for each file from the source — no language-specific config needed.\n\n```bash\n# Go (gin framework — 59 files, 0 test files, 56 LLM calls)\ncodedna init gin/ --extensions go --model deepseek/deepseek-chat\n```\n\n```go\n// auth.go — auth module.\n//\n// exports: BasicAuthForRealm | BasicAuthForProxy | BasicAuth | Accounts | AuthUserKey | AuthProxyUserKey\n// used_by: none\n// rules:   The authentication system uses constant-time comparison for credentials\n//          and requires all authorization logic to maintain this security property.\n// agent:   deepseek/deepseek-chat | deepseek | 2026-04-16 | codedna-cli | initial CodeDNA annotation pass\n\n// context.go — context module.\n//\n// exports: Cookie | FileAttachment | HTML | ... | (+135 more)\n// used_by: none\n// rules:   1. Context struct fields must maintain compatibility with gin's middleware chaining and abort mechanism.\n//          2. The mu mutex must be locked before accessing Keys map to ensure thread safety across concurrent requests.\n//          3. Changes to exported constants must preserve backward compatibility as they are part of the public API.\n// agent:   deepseek/deepseek-chat | deepseek | 2026-04-16 | codedna-cli | initial CodeDNA annotation pass\n```\n\n```bash\n# Ruby (Sinatra — 7 files, 6 LLM calls)\ncodedna init sinatra/lib --extensions rb --model deepseek/deepseek-chat\n```\n\n```ruby\n# base.rb — base module.\n#\n# exports: Sinatra | Request | Request#accept | ... | (+89 more)\n# used_by: none\n# rules:   The module must maintain compatibility with Rack's request interface\n#          and Sinatra's internal middleware dependencies.\n# agent:   deepseek/deepseek-chat | deepseek | 2026-04-16 | codedna-cli | initial CodeDNA annotation pass\n```\n\n> `*_test.go` files are automatically excluded. Exports are capped at 20 entries for readability.\n> Large files with many exports still show the full count: `(+135 more)`.\n\n---\n\n## How it works\n\nFour levels, like a zoom lens:\n\n```\n  Level 0              Level 1                Level 2              Level 3\n  .codedna        →    module header     →    function Rules:  →   # Rules: inline\n  project map          exports/used_by        + message:           above complex logic\n                       /rules/agent\n```\n\n> See also: [architecture diagram](docs/diagrams/codedna_architecture.svg)\n\n**`used_by:`** — reverse dependency graph. Who imports this file. The agent follows it instead of grepping.\n\n**`related:`** — cross-cutting links. Files that share the same logic without importing each other. Catches fixes that span multiple unrelated modules.\n\n**`rules:`** — hard constraints. Specific and actionable: *\"amount is cents not euros\"*, not *\"handle errors gracefully.\"*\n\n**`message:`** — agent-to-agent chat. Gets promoted to `rules:` when confirmed, or dismissed with a reason.\n\n```\n  Agent A writes code\n       │\n       ▼\n  message: \"rounding edge case\"     ← observation, not yet a rule\n       │\n       ▼\n  Agent B reads it (next session)\n       │\n       ├── confirmed?  YES  →  promoted to rules:\n       │\n       └── confirmed?  NO   →  dismissed with reason\n```\n\n> See also: [message lifecycle diagram](docs/diagrams/codedna_message_lifecycle.svg)\n\n**Header by language:**\n- **All languages** — full L1 header: `exports:` + `used_by:` + `rules:` + `agent:` + `message:`\n- **All source languages** — also get L2: function-level `Rules:` docstrings (Python, Go, TypeScript, PHP, Java, Kotlin, Ruby)\n- **Template engines** — L1 only (Blade, Jinja2, ERB, Handlebars, Razor, Vue SFC, Svelte)\n\n### Modes\n\nAll modes annotate L1 (module headers) + L2 (function Rules:) + `rules:` + `agent:`. The difference is:\n\n| Mode | `message:` | Semantic naming | For whom |\n|---|---|---|---|\n| **human** | ❌ | ❌ | Human teams — annotations are there, no inter-agent chat |\n| **semi** | ✅ | ❌ | Human + AI together — agents communicate via `message:` (default) |\n| **agent** | ✅ | ✅ | AI-first codebases — full protocol + `list_dict_users_from_db` naming |\n\n```bash\ncodedna mode semi     # default\ncodedna mode agent    # full protocol\n```\n\n> Full specification: [SPEC.md](./SPEC.md)\n\n---\n\n## Docs\n\n| | |\n|---|---|\n| [SPEC.md](./SPEC.md) | Protocol specification v0.9 |\n| [AGENTS.md](./AGENTS.md) | Protocol v0.9 for Codex, OpenCode, Aider, and other runtimes |\n| [docs/languages.md](docs/languages.md) | 13 programming languages, 29 extensions, template engines, framework awareness |\n| [docs/benchmark.md](docs/benchmark.md) | SWE-bench results, annotation integrity |\n| [docs/agent-tests.md](docs/agent-tests.md) | Real AI agent sessions — control vs CodeDNA on SWE-bench tasks |\n| [docs/experiments.md](docs/experiments.md) | Multi-agent experiments |\n| [CONTRIBUTING.md](./CONTRIBUTING.md) | Dev setup, contribution guide |\n\n---\n\n## Roadmap\n\nAll components are functional and tested — the protocol, CLI, and benchmark are actively evolving based on real-world usage and research feedback.\n\n| Area | What works | What's next |\n|---|---|---|\n| **Protocol v0.9** | `exports:` `used_by:` `related:` `rules:` `agent:` `message:` — all fields implemented | `related:` auto-generation via LLM, stale annotation detection |\n| **CLI** | `init` `update` `refresh` `check` `verify` `impact` `doctor` `manifest` `mode` `install` — 13 programming languages | PyPI publish, cross-cutting semantic verification |\n| **Benchmark** | 10 Django tasks (DeepSeek +17pp p=0.001), +13pp (Gemini Flash p=0.040) | Placebo condition, effect size, 20+ tasks, 5+ models |\n| **Integrations** | Claude Code plugin, Cursor, Copilot, Cline, OpenCode, Windsurf hooks | VS Code extension, GitHub Action for CI |\n| **Languages** | Python, PHP, TypeScript/JavaScript, Go, Java, Kotlin, Ruby, Rust, C#, VB.NET, Swift + 7 template families | More real-world testing on non-Python projects |\n| **Research** | Multi-agent experiments (98.2% adoption, 1.6x speedup), SWE-bench benchmark | arXiv preprint, placebo + ablation study |\n\n---\n\n<p align=\"center\">\n\nI built CodeDNA because AI agents kept making mistakes — not because they were wrong, but because they had no context. What if the context was already in the file?\n\nThe data is reproducible and the spec is open. [ko-fi.com/codedna](https://ko-fi.com/codedna)\n\n— Fabrizio\n\n</p>\n\n---\n\n## Star History\n\n<p align=\"center\">\n  <a href=\"https://www.star-history.com/?repos=Larens94%2Fcodedna&amp;type=timeline&amp;logscale=&amp;legend=bottom-right\">\n    <img src=\"https://api.star-history.com/svg?repos=Larens94/codedna&amp;type=Timeline&amp;legend=bottom-right\" alt=\"CodeDNA Star History timeline\" />\n  </a>\n</p>\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\n[MIT](./LICENSE)\n",
  "bytes": 27633,
  "sha": "237802234394ca8d36acd66017d210ff53d6e9d1e5bb00213b6de8bf10d6bf70",
  "repo_slug": "larens94/codedna",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_larens94_codedna_codedna_f054dd88/readme"
}