Skip to content
AXIOMAXIOM

AXIOM documentation

AXIOM takes a Plan from an agent, compiles it to a canonical content-addressed Manifest, runs checks over the whole change set, and applies it with a hash-gated two-phase commit that leaves a journal and, optionally, a signed attestation. One npm package — @codai/axiom-mcp — is an MCP server, a CLI, a PreToolUse hook and a GitHub Action. These pages are the reference for 2.2.x; the root README is the one-page tour, PLAN.md the canonical tracker of decisions and stories.

flowchart LR
  GS[Getting started] --> C[Concepts] --> G[Guides] --> R[Reference]
  GS --> I[Integrations]
  C --> D[Design & research]

Getting started

Section titled “Getting started”
Page Purpose
Install Every channel — npx, global bin, standalone binary, VS Code .vsix, GitHub Action, MCP Registry — with per-OS notes and how to verify downloads
Quickstart The 60-second flow: mcp.json, a first Plan, compile → check → apply, what .axiom/ now contains
Hooks axiom gate --stdin as a fail-closed PreToolUse hook: contract, wiring, profile file, latency budget

Concepts

Section titled “Concepts”
Page Purpose
Pipeline Plan → Manifest → checks → apply → journal, the two-phase commit as a sequence diagram, and the three content transports
Invariants The nine invariants every change must keep, each with what it protects against
Trust model Roots allowlist, no cwd fallback, fail-closed predicates, signing, anti-rollback, attestation
CAS The per-root content-addressed store and axiom gc

Guides

Section titled “Guides”
Page Purpose
Apply Guarantees, non-guarantees, .axiom/ layout, two-phase flow, rollback, dry-run, PR mode, Windows notes
Checks The 17 predicates with params, verdict semantics, built-in profiles, custom profiles
Signing DSSE envelopes, trust store, anti-rollback counter, root binding, CI key ceremony
Verify tree axiom verify --tree, --pre, in-toto attestation and how to verify it later
Snapshot axiom_repo_snapshot: deterministic inventory of a root, diffing two snapshots
Emitters template sources: determinism contract, the web@2.0.0 catalogue, authoring an emitter
Migrate axiom migrate v1: lifting a 1.x manifest into a v2 Plan

Reference

Section titled “Reference”
Page Purpose
CLI Every verb and flag, exit codes, examples
MCP tools The 17 tools, tasks and chunked plans, resources, transports, --wire eras
Plan format Field-by-field wire types: Plan, Manifest, Profile, CheckReport, ApplyResult, Journal
Error codes The closed ERROR_CODES enum with meaning and raising surface
Profiles Profile schema, built-in default / strict / permissive, extends, discovery, the gate profile
.axm syntax EBNF, semantics, heredocs, canonical form, LSP
Versioning Fixed version group, wire apiVersion, what is breaking

Integrations

Section titled “Integrations”
Page Purpose
Harnesses Claude Code / Copilot CLI / VS Code / Codex: hook wiring and MCP config side by side
GitHub Action dragoscv/axiom/action@v2 inputs, outputs, permissions, attestation
VS Code The .axm extension and language server, mcp.json
codai SWE harness default-on gate, agent-core risk classes, the eval arm
brivio guard.external over a 75-guard suite, tasks for the full run
metu repo.requireCompanion rules transcribed from skills

Design & research

Section titled “Design & research”
Page Purpose
v2 architecture The design document, annotated as built (2.2.x), with the package graph
Decisions D-01 … D-31 in one table, pointing at PLAN.md §1
Research Dated records from 2026-09-18/19: landscape, v1 inventory and test audit, red-team critique, mutation baseline, sibling-repo integration, 2.2 roadmap. Kept verbatim; only chat preambles were removed

Reading order for a new user

Section titled “Reading order for a new user”
  1. Install → Quickstart — ten minutes, a real apply on a scratch repo.
  2. Pipeline → Trust model — why confirmDigest, why roots, why fail-closed.
  3. Hooks and your harness in Harnesses — the always-on seatbelt.
  4. Checks → Profiles — make the gate say what your repo requires.
  5. Signing and Verify tree when you want proof in CI.

Reading order for a contributor

Section titled “Reading order for a contributor”
  1. .github/instructions/axiom-conventions.instructions.md and Invariants — what must never weaken.
  2. v2 architecture → Decisions — how it is built and why.
  3. Plan format → Error codes — the wire contract you are extending.
  4. The skill for your change: add-predicate, add-mcp-tool, add-golden-fixture, release-axiom, debug-apply-journal.
  5. CONTRIBUTING.md — the five green gates and the 18 repo guards.

[!NOTE] Links between pages are plain relative .md links; the docs site rewrites them at build time. Old top-level paths (docs/apply.md, docs/mcp_api.md, …) are three-line redirect stubs that the site build drops.