axiom

<div align="center">

<a href="https://dragoscv.github.io/axiom/"><img src="assets/brand/og-image.svg" width="100%" alt="AXIOM — the transactional write gate for coding agents"></a>

[![npm](https://img.shields.io/npm/v/%40codai%2Faxiom-mcp?label=npm&logo=npm)](https://www.npmjs.com/package/@codai/axiom-mcp)
[![downloads](https://img.shields.io/npm/dm/%40codai%2Faxiom-mcp?label=downloads)](https://www.npmjs.com/package/@codai/axiom-mcp)
[![CI](https://img.shields.io/github/actions/workflow/status/dragoscv/axiom/ci.yml?branch=main&label=CI&logo=github)](https://github.com/dragoscv/axiom/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/actions/workflow/status/dragoscv/axiom/release.yml?label=release&logo=github)](https://github.com/dragoscv/axiom/actions/workflows/release.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/dragoscv/axiom/badge)](https://scorecard.dev/viewer/?uri=github.com/dragoscv/axiom)
[![license](https://img.shields.io/badge/license-MIT-1c1917)](LICENSE)
[![docs](https://img.shields.io/badge/docs-dragoscv.github.io%2Faxiom-c2410c)](https://dragoscv.github.io/axiom/)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.dragoscv%2Faxiom-c2410c)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.dragoscv%2Faxiom/versions/latest)
[![node](https://img.shields.io/badge/node-%E2%89%A5%2022.14-1c1917?logo=node.js)](https://nodejs.org)

[Docs](https://dragoscv.github.io/axiom/) · [Quickstart](#quickstart-60-s) · [Tools](#tools) · [Architecture](#architecture) · [Packages](#packages) · [Contributing](CONTRIBUTING.md)

</div>

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

```mermaid
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

| Channel | Command | Platforms |
|---|---|---|
| Run without installing | `npx -y @codai/axiom-mcp mcp --root .` | anywhere with Node ≥ 22.14 |
| Global bin (`axiom`) — required for hooks | `npm i -g @codai/axiom-mcp` | anywhere with Node ≥ 22.14 |
| Standalone binary, no Node (from 2.2.1) | `curl -fsSL https://dragoscv.github.io/axiom/install.sh \| sh` | linux-x64 · linux-arm64 · darwin-arm64 · darwin-x64 |
| Standalone binary, no Node (from 2.2.1) | `irm https://dragoscv.github.io/axiom/install.ps1 \| iex` | win-x64 |
| VS Code `.axm` extension | `axiom-axm-<version>.vsix` on the [GitHub release](https://github.com/dragoscv/axiom/releases) | VS Code ≥ 1.138 |
| GitHub Action | `uses: dragoscv/axiom/action@v2` | ubuntu · macos · windows runners |
| MCP Registry | `io.github.dragoscv/axiom` | any registry-aware MCP client |

Binaries ship with `SHA256SUMS` and Sigstore provenance; npm packages carry npm provenance.
How to check them: [SECURITY.md](SECURITY.md#verifying-what-you-download).

## 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](packages/mcp/README.md)):

```json
{
  "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`:

```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):

```sh
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/plan-format.md) · [docs/reference/axm-syntax.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:

```json
{ "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](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:

```yaml
- 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](docs/guides/verify-tree.md).

## Tools

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

| Tool | What it does | Annotations |
|---|---|---|
| `axiom_plan_validate` | Validate a `Plan`; `ERR_*` codes with JSON pointers | read-only |
| `axiom_plan_compile` | `Plan` → `ManifestBundle` (inline blobs or CAS); writes only under `<root>/.axiom/` | act |
| `axiom_manifest_verify` | Recompute the canonical digest, verify every blob and, with a root, the DSSE signatures | read-only |
| `axiom_check` | Run a profile of predicates over a bundle; fails closed; verifies `preImage` against the tree | read-only |
| `axiom_check_start` | Same as `axiom_check`, returned immediately as a task (long `guard.external` suites) | read-only |
| `axiom_task_get` | Poll a task; `result` once `completed`, `error` once `failed`/`cancelled` | read-only |
| `axiom_task_cancel` | Abort a `working` task and kill its guard process trees | act |
| `axiom_plan_begin` | Open a chunked plan session for Plans over the 4 MiB call cap | act |
| `axiom_plan_add` | Append a chunk of `artifacts[]` to a session | act |
| `axiom_plan_seal` | Compile the assembled Plan through the same path as `axiom_plan_compile` | act |
| `axiom_apply_dry_run` | Containment + pre-image check + staging + unified diff; no user files touched | read-only |
| `axiom_apply` | Two-phase commit; requires `confirmDigest === manifestDigest`; single writer via `.axiom/lock` | destructive |
| `axiom_rollback` | Reverse-replay the journal of an applied manifest, scoped to its paths | destructive |
| `axiom_manifest_diff` | Added / removed / changed artifacts between two manifests | read-only |
| `axiom_axm_parse` | `.axm` DSL text → `Plan` with `{line, column}` diagnostics | read-only |
| `axiom_roots_list` | The allowlisted roots | read-only |
| `axiom_repo_snapshot` | Deterministic, content-addressed inventory of a root (`snapshotDigest`) | read-only |

Inputs, outputs, resources (`axiom://…`), transports (`--wire 2026|2025`) and the error
contract: [docs/reference/mcp-tools.md](docs/reference/mcp-tools.md). CLI verbs (`sign`, `trust`, `gc`, `migrate v1`,
`snapshot`, …): [packages/mcp/README.md](packages/mcp/README.md).

## Architecture

```mermaid
flowchart TB
  schema["@codai/axiom-schema<br/>Zod v4 · ERROR_CODES · JSON Schema"]
  canon["@codai/axiom-canon<br/>JCS · sha256 · in-toto · DSSE"]
  plan["@codai/axiom-plan<br/>compile · CAS ·