AIGX

<p align="center"> <img src="assets/logo.svg" alt="AIGX — AI Genome Exchange" width="560" /> </p> <p align="center"> <strong>The open, benchmark-validated context format for AI coding agents.</strong><br/> A <code>.aigx/</code> 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. </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/tools-MIT-22c55e.svg" alt="MIT"/></a> <a href="standard/LICENSE"><img src="https://img.shields.io/badge/spec-CC--BY--4.0-3b82f6.svg" alt="CC-BY-4.0"/></a> <a href="https://www.npmjs.com/package/@aigx/cli"><img src="https://img.shields.io/npm/v/@aigx/cli?label=npm%20%40aigx%2Fcli&color=22c55e" alt="npm @aigx/cli"/></a> <a href="https://pypi.org/project/aigx/"><img src="https://img.shields.io/pypi/v/aigx?label=PyPI&color=3b82f6" alt="PyPI"/></a> <a href="https://crates.io/crates/aigx"><img src="https://img.shields.io/crates/v/aigx?label=crates.io&color=f59e0b" alt="crates.io"/></a> <a href="standard/AIGX-1.1.md"><img src="https://img.shields.io/badge/spec-v1.1-8b5cf6.svg" alt="Spec v1.1"/></a> <a href="BENCHMARK.md"><img src="https://img.shields.io/badge/benchmark-n%3D60%20·%202%20models-f59e0b.svg" alt="Benchmark"/></a> </p> <p align="center"> <a href="#-quick-start">Quick start</a> · <a href="#-install-the-toolchain">Install</a> · <a href="#-the-proof">The proof</a> · <a href="#-using-aigx-with-your-stack">Use it with your stack</a> · <a href="standard/AIGX-1.1.md">Spec</a> · <a href="docs/aigx-in-60-seconds.md">60-second intro</a> </p>

---

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 <path>       # bounded output — 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

3 · Validate in CI

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

4 · Editor support — .aigx highlights everywhere

| Editor | How | |---|---| | VS Code / Cursor / Windsurf | Install AIGX Language Support — highlighting, file icons, snippets, rule-id autocomplete, hover on rule ids, go-to-definition, inline diagnostics, format, and AIGX: Resolve current file's boundary | | GitHub | .aigx already renders (via .gitattributes); a Linguist PR kit is ready for first-class support | | Sublime Text · TextMate · Zed | Ready-made configs in editors/ — all from one canonical TextMate grammar (source.aigx) |

5 · Programmatic (build on AIGX)

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.

6 · Wire any agent

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

| Cursor | Claude Code | GitHub Copilot | Windsurf | Aider | Generic | |---|---|---|---|---|---| | .cursor/rules/aigx.mdc | CLAUDE.md | .github/copilot-instructions.md | .windsurfrules | .aider.conf.yml | AGENTS.md |

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

---

🧬 How it works

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 →)

Anatomy of a genome

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

| Biology | AIGX | |---|---| | Genome — the code that builds & runs an organism | .aigx/ — the context that runs an agent in your codebase | | *