AXIOM

An agent describes a change set as a Plan. AXIOM compiles it to a canonical, content-addressed Manifest, runs checks over the whole set, and applies it with a hash-gated two-phase commit that leaves a journal and, optionally, a signed attestation. It ships as one npm package — @codai/axiom-mcp — that is an MCP server, a CLI, a PreToolUse hook and a GitHub Action.

Why

• Per change set, not per tool call. Harness hooks (Claude Code, Copilot, Cursor) decide one write at a time. A forty-file refactor is forty blind decisions; AXIOM checks the whole manifest first — "if you touch X you must also touch Y", dependency budgets, secrets, paths.
• Byte-exact. The manifest is JCS-canonical (RFC 8785) and holds only sha256 digests; apply demands the digest you inspected (confirmDigest), re-hashes every pre-image at commit, and rolls back to the byte-identical prior tree on any failure — on a tree several agents share.
• Provable. Every apply leaves a journal keyed by digest. Manifests can be DSSE-signed with pinned Ed25519 keys and anti-rollback counters; verify --tree proves a tree matches a manifest and emits an in-toto attestation that CI uploads to Sigstore.

What it does

flowchart LR
  subgraph entry [Entry points]
    direction TB
    MCP[MCP server<br/>stdio · Streamable HTTP]
    CLI[CLI<br/>axiom compile · check · apply]
    HOOK[PreToolUse hook<br/>axiom gate --stdin]
    GHA[GitHub Action<br/>dragoscv/axiom/action@v2]
  end
  P[Plan<br/>JSON or .axm] -->|compile| M[Manifest<br/>JCS · sha256 per file<br/>blobs · CAS · ref · patch]
  M -->|check| C[CheckReport<br/>pass · fail · error]
  C -->|apply · 2PC<br/>confirmDigest| T[Repository tree]
  T --> J[Journal · ApplyResult<br/>DSSE signature · in-toto attestation]
  J -.->|rollback| T
  entry --> P

Install

Then wire a repository in one idempotent step and check it:

npm i -g @codai/axiom-mcp
axiom init      # .vscode/mcp.json + PreToolUse hook (.github/hooks/axiom-gate.json or .claude/settings.json)
                # + .axiom/profiles/<repo>.json + .axiom/gate-profile.json + .gitignore lines
axiom doctor    # bin on PATH, hooks, gate p95 latency vs the 5 s hook timeout, lock, journals, profiles

init detects the harness (--harness auto|copilot|claude|codex|vscode), merges into existing JSON instead of overwriting (--force to replace), and writes only a note for Codex, which has no hook API. doctor exits 2 when a check fails. Per-harness files: docs/getting-started/install.md.

Binaries ship with SHA256SUMS and Sigstore provenance; npm packages carry npm provenance. How to check them: SECURITY.md.

Quickstart (60 s)

1. Point an MCP client at a repo — .vscode/mcp.json (Claude Desktop config is the same shape, see packages/mcp/README.md):

{
  "servers": {
    "axiom": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@codai/axiom-mcp", "mcp", "--root", "${workspaceFolder}"]
    }
  }
}

--root is an explicit allowlist and may repeat; there is no cwd or env fallback.

2. Write a Plan — plan.json:

{
  "apiVersion": "axiom.dev/v2",
  "kind": "Plan",
  "name": "hello",
  "intent": "Add a greeting module and document it.",
  "artifacts": [
    { "path": "src/hello.ts",
      "source": { "type": "inline", "content": "export const hi = () => 'hi';\n" } },
    { "path": "README.md", "op": "overwrite",
      "source": { "type": "inline", "content": "# hello\n" } }
  ],
  "checks": [{ "id": "no-secrets", "predicate": "content.noSecrets", "params": {} }]
}

3. Compile → check → apply from the CLI (the MCP tools do the same):

axiom compile plan.json --root . -o bundle.json        # → { manifestDigest: "sha256:…" }
axiom check   bundle.json --root .                     # → CheckReport, verdict pass|fail|error
axiom apply   bundle.json --root . --dry-run           # unified diff, nothing written
axiom apply   bundle.json --root . --confirm sha256:…  # two-phase commit, journal under .axiom/
axiom rollback sha256:… --root .                       # reverse-replay that journal entry

Plan fields, sources (inline, cas, ref, patch, template) and the .axm DSL: docs/reference/plan-format.md · docs/reference/axm-syntax.md.

Use it as a PreToolUse hook

axiom gate --stdin reads one harness payload, checks containment, path.deny/allow, content.noSecrets and content.maxBytes on the write target, scans shell commands for write primitives, and answers allow (exit 0) or deny (exit 2, JSON reason). Fail-closed; ~100 ms end to end. Claude Code:

{ "hooks": { "PreToolUse": [ { "matcher": "Write|Edit|MultiEdit|NotebookEdit",
  "hooks": [ { "type": "command", "command": "axiom gate --stdin", "timeout": 5 } ] } ] } }

Copilot CLI / VS Code wiring, profile file and the latency budget: docs/getting-started/hooks.md.

[!WARNING] Install the global bin for hooks. npx resolution takes seconds even with a warm cache, the harness times the hook out, and every harness fails open on timeout.

Use it in CI

Fail a pull request whose tree does not match the manifest an agent applied, and optionally upload an in-toto attestation:

- uses: dragoscv/axiom/action@v2
  with:
    bundle: .axiom/manifests/<hex>.json
    root: .
    attest: true   # needs permissions: id-token: write, attestations: write

Scope, --pre mode and how to verify the attestation later: docs/guides/verify-tree.md.

Tools

Eighteen MCP tools, each with annotations and an outputSchema; errors are isError results carrying a code from the closed ERROR_CODES enum — a handler never throws.