Introduction

The Problem

Every team has standards — "auth on all routes," "no secrets in code," "database access goes through the data layer." Today those rules live in someone's head and get enforced in code review... sometimes.

A route handler loses its middleware registration during a refactor. Now /admin/users serves data without checking credentials. Your unit tests pass. Your linter is silent. Nobody notices until a security audit three months later.

These standards violations are surprisingly common. Authentication gaps, broken architectural boundaries, hardcoded secrets, missing error handling. They slip through because no single tool can reason about them:

Unit tests verify individual functions, not cross-cutting standards
Linters match syntax patterns, but cannot reason about behavior across files
Code review catches them sometimes, but reviewers get tired and context-switch

What Axiomatic Does

Axiomatic lets you codify your team's standards in plain English and enforces them on every commit. Start with curated best-practice packs or write your own rules — an AI agent verifies them against your source code.

# axiomatic/auth-required.yml
condition: >
  All route handlers that access user data must require authentication.
  Public endpoints (health checks, login, registration) are exempt.
on:
  - "app/api/**/*.ts"
severity: error
tags: [security]

$ axm run

  auth-required ✓ pass (0.95 confidence, $0.03)
    Checked 14 route handlers in app/api/.
    All mutation endpoints use getServerSession() or withAuth().

When someone introduces a violation:

$ axm run

  auth-required ✗ fail (0.92 confidence, $0.04)
    Violations:
      app/api/users/delete/route.ts:12 - DELETE handler performs
      mutation without session check

Think of it as your team's standards, automatically enforced — it runs in CI, never gets tired, and checks every file on every commit. That's axiomatic.

What Makes It Different

Axiomatic enforces what other tools can't check:

Tool	Strength	Limitation
Linters (ESLint, golangci-lint)	Fast syntactic patterns	Cannot reason across files or about behavior
ArchUnit	Dependency rules in Java/C#	Language-specific, limited to import graphs
Semgrep	Structural AST matching	Matches patterns, not behavioral intent
Unit tests	Individual function correctness	Cannot verify cross-cutting properties
Code review	Catches nuanced issues	Inconsistent, expensive, doesn't scale
Axiomatic	Cross-cutting standards enforcement	LLM-based (costs $0.01-0.05/test with caching)

Axiomatic is best for standards that span multiple files and require understanding intent: authentication enforcement, architectural boundaries, security invariants, error handling consistency. If a linter, type checker, or unit test can verify the property deterministically, use that tool instead — Axiomatic is for the standards they can't enforce.

How It Works

You write conditions in plain English inside YAML files in your axiomatic/ directory.
When you run axm run, the agent reads each condition and uses sandboxed tools (read_file, grep, glob, list_dir) to explore your codebase.
The agent reasons about what it finds, iterating through files until it has enough evidence (typically 3-10 tool-call rounds).
It returns a verdict: pass or fail, with confidence and a list of violations pointing to specific files and lines.

Results are cached against file content hashes. Unchanged code is never re-analyzed, keeping costs near zero for subsequent runs.

Quick Start

curl -fsSL https://axiomatic.sh/api/install | sh

Platform (recommended) — free credits, best-practice packs, dashboard, shared agent memory:

axm login                # Sign in with GitHub ($5/month free credits)
axm install --suggest    # Install best-practice packs for your stack
axm run                  # Enforce your standards

Local — standalone, no account needed, bring your own API key:

export ANTHROPIC_API_KEY=sk-ant-...
axm init                 # AI generates starter tests for your codebase
axm run

A typical test costs $0.01-0.05 with Claude Haiku. Prompt caching and agent memory cut costs 60-80% — re-runs on unchanged code are free. See the Quickstart for a full walkthrough.

Real-World Examples

Security: No Hardcoded Secrets

condition: >
  No source files should contain hardcoded secrets, API keys, passwords,
  or tokens. Patterns like "sk-", "ghp_", "password=", and Base64-encoded
  credentials should not appear in source. Environment variable references
  (process.env.X, os.environ) are acceptable.
on:
  - "src/**/*.{ts,tsx,js,jsx}"
severity: error
tags: [security]

Architecture: Database Layer Boundary

condition: >
  No files outside of src/data/ should import from the Prisma client
  directly or use prisma.* calls. All database access must go through
  the repository functions exported from src/data/.
on:
  - "src/**/*.ts"
severity: error
tags: [architecture]

Error Handling: Meaningful Error Context

condition: >
  Error messages returned to users should include enough context to
  diagnose where the problem originated. Bare "Something went wrong"
  or generic error strings without request-specific details are not
  acceptable in production error handlers.
on:
  - "src/api/**/*.ts"
severity: warning
tags: [code-quality]

Next Steps

Quickstart - get up and running in under 5 minutes (platform or local)
First Test - understand results, write a real test, see the before/after
Writing Tests - learn to write effective conditions, avoid common pitfalls, and see examples across languages
Dashboard - track results, manage orgs, monitor confidence trends
CI/CD Integration - run Axiomatic in GitHub Actions, GitLab CI, and other pipelines
CLI Reference - complete command and flag reference

Introduction

On this page