Install CodeDNA

One CLI connects every coding agent to the same protocol, annotates all supported languages, and verifies the setup.

CodeDNA v0.912 languagesUpdated August 2026

Overview

Use the same setup for a new repository or an existing codebase. No model API key is required for the structural pass.

Install the CodeDNA CLI

Provides language detection, annotation, verification, and the project installer.

Connect agents and annotate the repository

Installs native instructions/hooks, then adds CodeDNA headers to existing source files.

Tool	Option	Enforcement
Claude Code	claude	Active
Codex	codex	Instructions + Git gate
Cursor	cursor	Active v1.7+
GitHub Copilot	copilot	Active
Cline	cline	Active v3.36+
OpenCode	opencode	Active
Windsurf	windsurf	Instructions only
Aider	aider	Instructions + Git gate
Antigravity	agents	Instructions only v1.20.3+

Active enforcement = hooks validate annotations automatically on every file write/edit, regardless of session length or task complexity. The agent cannot skip annotations even in long or complex sessions.

Quick Setup

Run these commands from the repository root:

terminal

pipx install git+https://github.com/Larens94/codedna.git

codedna install --path . --tools codex --no-wiki-sync
codedna init . --no-llm
codedna doctor --path .

Replace codex with one or more values from the table. Mixed teams can use --tools claude codex opencode.

Claude Code

Active enforcement

terminal

codedna install --path . --tools claude --no-wiki-sync

Installs CLAUDE.md + 4 enforcement hooks + .claude/settings.local.json. Claude Code reads CLAUDE.md automatically; hooks validate every write.

What the four hooks do

Hook	Event	What it does
SessionStart	Session begins	Reads .codedna, injects project name and module count into context
PreToolUse	Before every .py write/edit	Reminds agent to read docstring and plan agent: update
PostToolUse	After every .py write/edit	Validates all 4 fields exist and agent: has today's date
Stop	Session ends	Reminds to update .codedna with a new agent_sessions entry

Requires jq: brew install jq (macOS) or apt install jq (Linux).

Settings file location

File	Committed?	Use when
.claude/settings.local.json	❌ gitignored	Personal setup — each developer configures locally
.claude/settings.json	committed	Team / CI — shared via the repo, always present

Codex

Instructions + Git gate

terminal

codedna install --path . --tools codex --no-wiki-sync

Installs the cross-vendor AGENTS.md, the local manifest, and the Git pre-commit gate. Codex discovers the repository instructions automatically and follows the same protocol as every other agent.

Cursor

Active enforcement v1.7+

terminal

codedna install --path . --tools cursor --no-wiki-sync

Installs .cursorrules + hook scripts in .cursor/hooks/. Cursor runs hooks automatically on file edits and when the agent stops.

Hook	Event	What it does
after-file-edit.sh	After every file edit	Validates CodeDNA header on source files
stop.sh	Agent finishes	Reminds to update .codedna and commit with AI trailers

For Cursor v0.43+, you can also place rules under .cursor/rules/: mkdir -p .cursor/rules && cp .cursorrules .cursor/rules/codedna.mdc

GitHub Copilot

Active enforcement

terminal

codedna install --path . --tools copilot --no-wiki-sync

Installs .github/copilot-instructions.md + .github/hooks/hooks.json + .github/hooks/codedna.sh. Copilot runs hooks automatically at session boundaries and after every tool use.

Hook	Event	What it does
session_start	Session begins	Reads .codedna, injects project context
post_tool_use	After every file write/edit	Validates CodeDNA header on source files
session_end	Session finishes	Reminds to update .codedna and commit with AI trailers

Cline

Active enforcement v3.36+

terminal

codedna install --path . --tools cline --no-wiki-sync

Installs .clinerules + hook scripts in .clinerules/hooks/. Cline runs hooks on task start and after every file write/edit.

Hook	Event	What it does
TaskStart.sh	Task begins	Reads .codedna, injects project context
PostToolUse.sh	After every file write/edit	Validates CodeDNA header on source files

OpenCode

Active enforcement

terminal

codedna install --path . --tools opencode --no-wiki-sync

Installs AGENTS.md + .opencode/plugins/codedna.js. Both load automatically at the next opencode startup.

File	What it does
AGENTS.md	CodeDNA v0.9 instructions — loaded automatically as system prompt
.opencode/plugins/codedna.js	After every file write → warns on missing headers in comment-based languages. At session end → reminds to update .codedna and commit with AI trailers. Native AXL validation runs through the CLI.

Fallback: if no AGENTS.md is found, OpenCode falls back to CLAUDE.md automatically — projects using the Claude Code integration work out of the box.

Windsurf

Instructions + Git gate

terminal

codedna install --path . --tools windsurf --no-wiki-sync

Installs .windsurfrules — Windsurf reads it automatically and applies CodeDNA rules to all Cascade sessions.

Windsurf supports post-response hooks (observability only) — no blocking enforcement is available. The agent receives instructions but nothing validates compliance automatically.

Aider

Instructions only

terminal

codedna install --path . --tools aider --no-wiki-sync

Installs AGENTS.md. Load it as Aider's read-only conventions file:

aider --read AGENTS.md

Or add permanently to .aider.conf.yml:

read: AGENTS.md

Antigravity

Instructions only v1.20.3+

terminal

codedna install --path . --tools agents --no-wiki-sync

Antigravity is Google's agentic IDE. CodeDNA targets two of its native extension points so the protocol is loaded automatically and available on demand.

File	Mechanism	When it loads
AGENTS.md (repo root)	Cross-vendor rules	Always-on — auto-loaded as system prompt every session (Antigravity v1.20.3+)
.agent/workflows/codedna.md	Antigravity workflow	On-demand — type /codedna in agent chat

Note: Antigravity uses .agent/ (singular), not .agents/. Precedence inside Antigravity: GEMINI.md > AGENTS.md > .agent/rules/. CodeDNA ships rules in AGENTS.md for portability across IDEs (Claude Code, OpenCode, Cursor read the same file). See the official rules & workflows docs.

CLI — Annotate an existing codebase

Bulk-annotate all files in a project from the terminal. Supports local models via Ollama at zero cost.

pipx install git+https://github.com/Larens94/codedna.git

# Free — structural only, no AI
codedna init /path/to/project --no-llm

# Free — local model via Ollama
codedna init /path/to/project --model ollama/llama3

# Paid — Anthropic Haiku (~$1-3 for a Django project)
ANTHROPIC_API_KEY=sk-... codedna init /path/to/project --model claude-haiku-4-5-20251001

Commands

Command	What it does
codedna init PATH	First-time annotation — L1 module headers + L2 function Rules:. Auto-detects languages.
codedna update PATH	Incremental — only unannotated files, safe to re-run
codedna refresh PATH	Recalculate exports: + used_by: via AST/tree-sitter. Zero LLM cost. Preserves rules:/agent:.
codedna check PATH	Coverage report without modifying files. Exit code 1 if incomplete — works in CI.
codedna doctor --path PATH	Onboarding health check for the manifest, parsers, hooks, CI, and lock configuration.
codedna impact FILE --path PATH	Show rules and transitive callers before changing a public contract.
codedna verify PATH	Read-only structural drift gate for exports: and used_by:. Add --json in CI.
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 wiki bootstrap PATH	Generate 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. Hook to post-commit to keep it current.
codedna self-update	Upgrade the CLI itself via pip install --upgrade --force-reinstall. Refuses to clobber editable/dev checkouts unless --force. Use --check for read-only version display.

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

wiki: field — two paths

Obsidian graph view of a project annotated with CodeDNA

Supported models

Provider	Example	Cost
None	--no-llm	Free — structural only (exports + used_by)
Ollama (local)	ollama/llama3	Free
DeepSeek	deepseek/deepseek-chat	~$0.40 / 200 files
Anthropic	claude-haiku-4-5-20251001	~$1–3 / project
OpenAI	openai/gpt-4o-mini	Low
Google	gemini/gemini-2.0-flash	Low

Language Annotation Format

Logical field names are identical across all languages. Comment-based languages use their native comment syntax; experimental AXL support uses structured opcode frames. CodeDNA registers 28 extensions across Python, TypeScript, JavaScript, Go, PHP, Java, Kotlin, Ruby, Rust, C#, Swift, AXL, and seven template families. Explore representative formats below:

Python

"""docstring"""

TypeScript

/** JSDoc */

JavaScript

/** JSDoc */

// before package

Rust

//! inner doc

Java

/** Javadoc */

Ruby

# comment block

PHP

// comment block

Blade

Python

Module docstring — first thing in the file, before any imports

"""filename.py — purpose in 15 words or fewer.

exports: public_fn(arg) -> ReturnType
used_by: caller.py → caller_fn | other.py → other_fn
related: similar_logic.py — shares same pattern (no import link)
rules:   hard constraint agents must never violate
agent:   claude-sonnet-4-6 | anthropic | 2026-03-24 | s_20260324_001 | what was done
         message: "open hypothesis for the next agent"
"""

import os
from typing import Optional

`message:` — Agent-to-Agent Chat (v0.9)

The message: sub-field is a conversational layer between agents. Use it for observations not yet certain enough to become rules:.

Lifecycle: a message is either promoted to rules: (reply @prev: promoted to rules:) or dismissed (@prev: not applicable because...). Always append-only.

Works at both levels: Level 1 (module docstring) and Level 2 (function docstring) — so agents using a sliding window still receive it.

Function-level (Level 2)

def my_function(arg: Type) -> ReturnType:
    """Short description.

    Rules:   constraint — what must or must not happen here
    message: model-id | YYYY-MM-DD | observation for next agent
    """
    ...

Semantic naming

# good  →  type_shape_domain_origin
list_dict_users_from_db = get_users()
str_html_report_rendered = render(ctx)
int_cents_price_from_request = req.json["price"]

# avoid
data = get_users()
result = render(ctx)

TypeScript / JavaScript

JSDoc block — before the first import

/**
 * filename.ts — purpose in 15 words or fewer.
 *
 * exports: publicFn(arg): ReturnType
 * used_by: caller.ts → callerFn
 * rules:   hard constraint agents must never violate
 * agent:   claude-sonnet-4-6 | anthropic | 2026-03-24 | s_20260324_001 | what was done
 *          message: "open hypothesis for the next agent"
 */

import { something } from './something';

Function-level (Level 2)

/**
 * Short description.
 *
 * Rules:   constraint
 * message: model-id | YYYY-MM-DD | observation
 */
export function myFunction(arg: Type): ReturnType { ... }

Go

Block comment — before the package declaration

// filename.go — purpose in 15 words or fewer.
//
// exports: FuncName(arg Type) ReturnType
// used_by: caller.go → CallerFn
// rules:   hard constraint agents must never violate
// agent:   claude-sonnet-4-6 | anthropic | 2026-03-24 | s_20260324_001 | what was done
//          message: "open hypothesis for the next agent"

package mypackage

Function-level (Level 2)

// MyFunction does X.
//
// Rules:   constraint
// message: model-id | YYYY-MM-DD | observation
func MyFunction(arg Type) ReturnType { ... }

Rust

Inner doc comment — at the top of the file

//! filename.rs — purpose in 15 words or fewer.
//!
//! exports: pub_fn(arg: Type) -> ReturnType
//! used_by: caller.rs → caller_fn
//! rules:   hard constraint agents must never violate
//! agent:   claude-sonnet-4-6 | anthropic | 2026-03-24 | s_20260324_001 | what was done
//!          message: "open hypothesis for the next agent"

use std::collections::HashMap;

Java

Javadoc block — before the class declaration

/**
 * ClassName.java — purpose in 15 words or fewer.
 *
 * exports: publicMethod(arg Type): ReturnType
 * used_by: CallerClass.java → callerMethod
 * rules:   hard constraint agents must never violate
 * agent:   claude-sonnet-4-6 | anthropic | 2026-03-24 | s_20260324_001 | what was done
 *          message: "open hypothesis for the next agent"
 */
public class ClassName { ... }

Ruby

Comment block — at the top of the file

# filename.rb — purpose in 15 words or fewer.
#
# exports: public_method(arg) -> ReturnType
# used_by: caller.rb → caller_method
# rules:   hard constraint agents must never violate
# agent:   claude-sonnet-4-6 | anthropic | 2026-03-24 | s_20260324_001 | what was done
#          message: "open hypothesis for the next agent"

require 'json'

PHP

// comment block — after <?php, NOT PHPDoc

<?php
// UserController.php — Handles user CRUD endpoints.
//
// exports: UserController | UserController::index() | UserController::store(Request $request)
// used_by: routes/web.php
// related: app/Models/User.php — shared user domain logic
// rules:   must extend App\Http\Controllers\Controller
// agent:   codedna-cli | codedna-cli | 2026-04-18 | codedna-cli | initial CodeDNA annotation

namespace App\Http\Controllers;

Blade templates

{{-- layout.blade.php — Base application layout.
--
-- exports: none
-- used_by: none
-- rules:   @yield('content') is required — child views must define this section
-- agent:   codedna-cli | codedna-cli | 2026-04-18 | codedna-cli | initial CodeDNA annotation
--}}

<!DOCTYPE html>

Blade (Laravel)

{{-- --}} comment block — at the top of the file

{{-- layout.blade.php — Base application layout.
--
-- exports: none
-- used_by: none
-- rules:   @yield('content') is required — child views must define this section
-- agent:   codedna-cli | codedna-cli | 2026-04-18 | codedna-cli | initial CodeDNA annotation
--}}

<!DOCTYPE html>
<html>

JavaScript

JSDoc block — before the first import or export

/**
 * filename.js — purpose in 15 words or fewer.
 *
 * exports: publicFn(arg)
 * used_by: caller.js → callerFn
 * rules:   hard constraint agents must never violate
 * agent:   claude-sonnet-4-6 | anthropic | 2026-03-24 | s_20260324_001 | what was done
 *          message: "open hypothesis for the next agent"
 */

const something = require('./something');

Hook Events Reference

All CodeDNA hook scripts follow the same pattern: receive JSON via stdin, write feedback to stdout, exit 0.

Event	Claude Code	Cursor	Copilot	Cline
Session / task start	SessionStart	—	sessionStart	TaskStart
Before write/edit	PreToolUse	—	—	—
After write/edit	PostToolUse	afterFileEdit	postToolUse	PostToolUse
Session / agent end	Stop	stop	sessionEnd	—

All hook scripts use tools/validate_manifests.py for validation — downloaded automatically by install.sh.

Claude Code Plugin Available

terminal

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

Important: After installing, start a new session (close and reopen Claude Code, or run /clear). Slash commands are only available after restarting.

No API key. No extra cost. Uses your existing Claude subscription. Adds interactive setup via /codedna:init + coverage check via /codedna:check + architectural map via /codedna:manifest + impact analysis via /codedna:impact.

Was this page helpful?Yes No

Install CodeDNA

Overview

Quick Setup

Claude Code

What the four hooks do

Settings file location

Codex

Cursor

GitHub Copilot

Cline

OpenCode

Windsurf

Aider

Antigravity

CLI — Annotate an existing codebase

Commands

Supported models

Language Annotation Format

Python

message: — Agent-to-Agent Chat (v0.9)

Function-level (Level 2)

Semantic naming

TypeScript / JavaScript

Function-level (Level 2)

Go

Function-level (Level 2)

Rust

Java

Ruby

PHP

Blade templates

Blade (Laravel)

JavaScript

Hook Events Reference

Claude Code Plugin Available

`message:` — Agent-to-Agent Chat (v0.9)