The open, benchmark-validated context format for AI coding agents.
A .aigx/ genome describes how your repo works — rules, per-file boundaries, gotchas — so any AI agent inherits your conventions and behaves like a senior engineer who already knows the code.

Quick start · Install · The proof · Use it with your stack · Spec · 60-second intro

AIGX (AI Genome Exchange) stores a codebase's AI-agent rules in a centralized .aigx/ directory with a per-file boundary index — and injects nothing into your source code. To our knowledge it is the only context format ever validated in a controlled benchmark, where it was the only format to rank first on both a weaker and a stronger model (Claude Haiku 4.5 and Sonnet 4.6, n=60) while surviving ~24 deliberate attempts to beat it.

Straight about the statistics (up front): at n=60 the top formats are a statistical tie on the composite mean — AIGX is not a blowout. Its defensible edge is being the most consistent across models, the most robust under challenge, the simplest to author, and the only option measured at all. Full scope, limitations & critique responses →

_{Spec v1.1 (CC-BY-4.0) · Tools MIT · Tool-agnostic · Published on npm · PyPI · crates.io · Last updated 2026-06-20}

One command scaffolds a genome and wires up your AI agent(s):

npm create aigx
# or: npx create-aigx   (same thing)

It's interactive — pick Cursor / Claude Code / Copilot / Windsurf / Aider / AGENTS.md, choose CI, done:

your-repo/
├── .aigx/
│   ├── protocol.aigx        ← the read protocol every agent loads first
│   ├── product.aigx         ← product context + freshness clause
│   ├── architecture.aigx    ← per-concern rules  (ARCH-* ids)
│   ├── engineering.aigx     ← hard-correctness invariants (ENG-* ids)
│   ├── files.aigx           ← ★ the per-file boundary index — fill this in
│   └── agent.aigx           ← self-maintenance rules for agents
├── .cursor/rules/aigx.mdc · CLAUDE.md · AGENTS.md · .windsurfrules · .aider.conf.yml
└── .github/{copilot-instructions.md, workflows/aigx-validate.yml}

Your source code is untouched. Then fill in three things — files.aigx (the keystone), your rules in architecture.aigx, and product.aigx — and validate with aigx lint. The 60-second intro and authoring guide walk you through it; a complete real-world genome is in examples/sourcing-app/.

AIGX ships three independent reference implementations (Node, Python, Rust) — install from whatever registry you already live in. They're held in lock-step by a conformance suite.

# zero-install runs, too:
npx @aigx/cli lint
npx @aigx/cli resolve src/features/auth/login.ts

Naming note: npm reserves the bare aigx name, so the npm CLI is @aigx/cli — but the installed command is aigx everywhere. On PyPI and crates.io the package is plain aigx.

We built a controlled benchmark: one real TypeScript codebase with planted traps (deep-import violations, dependency cycles, cross-tenant leaks, cache-ordering bugs, hallucination — 10 hard pitfalls), held constant, with only the context format varying and semantic parity machine-enforced (every format carries the identical rules). The subject is an autonomous agent that greps, edits, and runs tests. Scoring is deterministic and tamper-proof.

AIGX ranks first on mean, pass@1, and hidden-test pass on both models — but the honest story is consistency, not margin. Markdown is great on Sonnet yet near-last on Haiku; XML is the rough reverse. AIGX is the only format first on both tiers — and it survived ~24 challenger variants across 6 research rounds, every one of which failed to beat it.

🔬 Full method, models, sample sizes, raw data, and the challenger log → BENCHMARK.md · honest caveats → docs/limitations.md

npm create aigx           # pick your agent(s) + CI, then fill in files.aigx
npm create aigx -- --yes  # non-interactive: scaffold everything (great for CI)

Same six commands whether you installed via npm, pip, or cargo:

aigx init                 # scaffold a .aigx/ genome (also interactive)
aigx lint                 # validate: required files, resolving checks, no stale paths, no dup ids
aigx resolve <path>       # O(1) — print one file's boundary (role · forbid · gotcha · checks)
aigx doctor               # environment + genome health check
aigx format [--check]     # parity-safe whitespace normalization
aigx check-conformance    # report your genome's conformance level (G1–G4 + recommended)

$ aigx resolve src/features/meetings/bookMeeting.ts
Applicable genome: .aigx
Role:   Book a meeting (validate slot + contact)
Forbid: NEVER import @/features/suppliers/internal/*   [CRIT]
Gotcha: get contact_email from the suppliers PUBLIC api, never the internal mapper
Checks: ARCH-no-deep-imports, DATA-integer-cents, TEST-failing-first

The genome can't silently rot — wire the validator into CI so a moved/renamed file fails the build:

# .github/workflows/aigx-validate.yml
- run: npx --yes @aigx/cli lint        # or: pipx run aigx --root .  ·  or: cargo run -p aigx -- lint

npm i @aigx/parser @aigx/lint

import { parseGenome } from '@aigx/parser'
import { lint } from '@aigx/lint'

const model = parseGenome('.')          // → canonical JSON data model (matches the spec's schema)
const { ok, errors } = lint('.')        // → the same checks as the CLI / aigx-lint

Python (pip install aigx) exposes the validator as aigx-lint and as import aigx_lint. For MCP clients and codebase-memory agents, resolve a boundary as JSON before graph/search context — see JIT Context Hydration.

npm create aigx configures these for you; or copy one file from integrations/:

For a custom agent, paste the one-paragraph addendum from the spec §12.3.

flowchart TD
    A["Agent gets a task<br/>e.g. 'add a field to bookMeeting'"] --> B["Reads .aigx/protocol.aigx<br/>(the read order)"]
    B --> C["Reads the concern files<br/>the task touches"]
    B --> D["For EACH file it will edit,<br/>looks up its entry in<br/>.aigx/files.aigx"]
    D --> E["Gets the binding constraint<br/>at the edit site:<br/>forbid · gotcha · check-ids"]
    C --> F["Implements the change"]
    E --> F
    F --> G["Verifies every &lt;check&gt; id<br/>before declaring done"]
    style A fill:#1e293b,stroke:#475569,color:#e2e8f0
    style D fill:#7c2d12,stroke:#ea580c,color:#fed7aa
    style E fill:#7c2d12,stroke:#ea580c,color:#fed7aa
    style G fill:#14532d,stroke:#22c55e,color:#bbf7d0

The magic is per-file addressability. Agentic models read selectively — they grep, open the file they're editing, and rarely re-scan a whole rule doc. AIGX makes the binding constraint for that file retrievable in one lookup (files.aigx), instead of buried in prose — and keeps it out of your source. We tested all three placements (global prose, inline-in-source, addressed index); the addressed index won, inlining lost. (the principles →)

<!-- .aigx/architecture.aigx — rules with stable, citable ids -->
<aigx-architecture>
  <rule id="ARCH-no-deep-imports">Import features only through their public barrel. Deep imports are forbidden.</rule>
</aigx-architecture>

<!-- .aigx/files.aigx — THE KEYSTONE: the binding constraint per edited file -->
<aigx-files>
  <file path="src/features/auth/login.ts" domain="auth">
    <role>Handle login — validate credentials, issue a session</role>
    <forbid pri="CRIT">NEVER import @/features/billing/internal/*</forbid>
    <gotcha>token expiry is checked at read-time, not issue-time</gotcha>
    <check>ARCH-no-deep-imports ENG-tenant-scope</check>
  </file>
</aigx-files>

AIGX is a real, citable standard — not just a convention:

• standard/AIGX-1.1.md — the normative spec (20 sections, RFC 2119 language)
• AIGX-1.1.abnf — formal grammar (RFC 5234) · AIGX-1.1.schema.json — canonical JSON data model
• media-type-registration.md — IANA template for application/aigx
• conformance · security · interoperability · change-control

Dual-licensed: spec text CC-BY-4.0, reference tools MIT — so anyone can reimplement AIGX in any language, freely. (SPEC.md is the informal, example-led companion.)

AIGX isn't out to replace AGENTS.md — it's the genome layer: a richer, measured, per-file-precise substrate you author once and can export down to a flat AGENTS.md/CLAUDE.md when a tool needs it.

What is AIGX in one sentence? An open context format that stores a codebase's AI-agent rules in a centralized .aigx/ directory with a per-file boundary index — the only such format validated to win a controlled benchmark.

How is it different from AGENTS.md / CLAUDE.md? Those are usually one flat prose file. AIGX adds a per-file boundary index so an agent gets the binding constraint at the edit site, and it's tool-agnostic and exports down to those formats.

Does it put comments in my source code? No — deliberately. We measured that in-source headers hurt a strong model. The genome lives entirely in .aigx/; your diffs stay clean.

Is it really better, or are the top formats close? Honestly, at matched power the top formats are a tight cluster. AIGX's edge is robustness, cross-model generalization, and simplicity — and being the one design that survived every challenger.

Can I use it commercially / build tools on it? Yes — tools are MIT, the spec is CC-BY-4.0. No permission needed.

Plus zero-dep tools in tools/: aigx-lint (validator/resolver), aigx-sync (rename pre-commit hook), aigx-mcp (stdio MCP bridge), aigx-export (safe .aigx/Markdown serializer).

aigx/
├── standard/        ← the NORMATIVE standard (spec, ABNF, JSON schema, IANA, conformance…)
├── SPEC.md          ← informal, example-led spec (points to standard/)
├── packages/        ← npm workspace: @aigx/cli, @aigx/parser, @aigx/lint
├── bin/create-aigx.mjs · pyproject.toml · crates/aigx/   ← npm / PyPI / Cargo entry points
├── editors/         ← VS Code ext, TextMate grammar, Sublime, Zed, Linguist kit
├── tools/           ← aigx-lint, aigx-sync, aigx-mcp, aigx-export (zero-dep)
├── tests/conformance/  ← cross-validator suite (Python · Node · Rust agree)
├── integrations/    ← Cursor, Claude Code, Copilot, Windsurf, Aider, AGENTS.md, CI
├── examples/        ← sourcing-app (full), minimal
├── docs/            ← 60-seconds, authoring guide, principles, limitations, migration, jit-hydration
├── .aigx/           ← this repo's own genome (AIGX uses AIGX)
└── RELEASING.md     ← how each package is published

• ✅ Spec v1.1 — stable; normative standard with ABNF, JSON schema & IANA media type
• ✅ Published — npm (@aigx/cli, create-aigx, @aigx/parser, @aigx/lint) · PyPI (aigx) · crates.io (aigx)
• ✅ 3 reference validators (Node · Python · Rust) agreeing on a conformance suite
• ✅ Editor support — VS Code extension + one canonical grammar reused across Sublime/TextMate/Zed/Linguist + GitHub highlighting
• ✅ Benchmark — n=60 on two models, reproducible, honest
• 🔜 VS Code Marketplace + Open VSX listing · Language Server (LSP) · monorepo-scale benchmark · Python/Go examples

Want to help? CONTRIBUTING.md · open an issue · star the repo.

@software{aigx2026,
  title   = {AIGX: AI Genome Exchange — A Benchmark-Validated Context Format for AI Coding Agents},
  author  = {Parisotto, Grégory},
  year    = {2026},
  url     = {https://github.com/Lolner95/AIGX},
  license = {MIT (tools), CC-BY-4.0 (spec)}
}

Reference tools: MIT. Specification text: CC-BY-4.0. Open spec + permissive tools, so AIGX can be adopted and reimplemented by anyone, for anything.

_{Built from a research-grade benchmark. The genome of your codebase, for the age of AI agents. 🧬}