I’ve been working in software development for 15 years, but this is my first independent open-source publication. It stems from a practical frustration I believe many of you share.
Working with AI coding tools and agent orchestrators (like Google Antigravity, Anthropic(claude), or Cursor), I noticed something: models write single-file code excellently, but they struggle to navigate and tend to hallucinate as soon as they need to understand the architecture of an entire multi-file project.
To try and solve this, I built CodeDNA (currently v0.7 and heavily experimental).
It’s a true inter-agent communication protocol.
The idea is that the source file itself becomes the asynchronous communication channel between different LLMs. When an agent modifies the code, it updates the annotations. When another agent (perhaps from a different vendor) opens that file months later, it "decodes" this DNA and knows exactly how to move.
CodeDNA is inspired by how the human eye works. To understand a complex system, we need to focus both from far away and up close. Instead of relying on heavy RAG systems or infinite prompts, the code itself becomes the shared memory, structured across multiple levels of "zoom":
🔭 The view from far away: A structural map of the project (a .codedna file) that the agent reads before opening any source code. 🔬 The view from close up: Architectural context (like who uses the file, used_by:, and domain rules, rules:) embedded directly into the docstrings.
📊 Early data (the good and the bad): I ran zero-shot benchmarks on 5 real Django issues (SWE-bench). On tasks with clear dependency chains, CodeDNA improved navigation precision by +13%. The goal of this scaffolding is exactly this: to eventually allow smaller, cheaper models to approach the navigation performance of the most expensive frontier models. However, on cross-cutting modifications, the measured improvement so far is ~0%. No magic wands here, and it’s all documented transparently in the spec.
🛠️ My ask: try it out. Because this is a purely experimental project, the best way to see if it makes sense or hits unbreakable limits is to have other developers test it in the field.
There's a 2-minute setup script that configures CodeDNA directly for your favorite AI tool.
I only ask this: install it on a side project, let it annotate a few files, and see if your AI starts making fewer context errors. Above all: break it and give me brutal feedback.
Here are the links to the project! 👇
📦 Repository & 2-min Quickstart: https://github.com/Larens94/codedna
📄 Full v0.7 Specs & Benchmarks: https://github.com/Larens94/codedna/blob/main/SPEC.md
This is an open experiment, so I'm happy to answer any technical questions, doubts, or critiques here in the comments!
Top comments (0)