AIGX

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

---

🚀 Quick start

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/.

---

📦 Install the toolchain

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.

You want…	Install	Gives you
Scaffold a genome	npm create aigx	the interactive scaffolder (create-aigx)
The CLI (Node)	npm i -g @aigx/cli	the aigx command (@aigx/cli)
The CLI / validator (Python)	pip install aigx	aigx + aigx-lint (PyPI)
The CLI / validator (Rust)	cargo install aigx	the aigx binary (crates.io)
Editor support	VS Code Marketplace → AIGX Language Support	highlighting, hover, diagnostics, go-to-def (editors/vscode)
Libraries (Node)	npm i @aigx/parser @aigx/lint	programmatic parse + validate

# 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.

---

🔬 The proof

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.

Format	Sonnet 4.6 mean	pass@1	hidden	Haiku 4.5 mean	pass@1	hidden
🧬 AIGX	95.4	0.92	98.6%	93.5	0.78	96.0%
Markdown	95.1	0.80	96.4%	92.2	0.70	93.6%
XML	93.1	0.80	93.8%	92.3	0.75	93.3%
In-source headers	94.6	0.80	96.1%	92.4	0.67	90.2%

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

---

🛠 Using AIGX with your stack

1 · Scaffold (interactive)

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

2 · The aigx CLI

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        # bounded output — print one file's boundary (role · forbid · gotcha · checks)
ai