Axiom – blocks AI agents from inventing limits your code never defined

Axiom, a new local guardrail tool from the axiom-csc project, released at version v1.2.2, runs as a pre-write hook in Claude Code and Cursor and as a stdin/stdout filter for any agent that can pipe tool calls through a subprocess, blocking writes before they happen with zero dependencies and no API keys. The tool's three passes — Noema for regex-based constraint extraction, Lemma for deterministic Python evaluation against project invariants, and Manam for tri-state TRUE/FALSE/UNKNOWN logic — halt the agent on UNKNOWN and emit an AxiomConstraintViolation on FALSE, though the project states its detection is regex and AST-pattern based rather than semantic and that a motivated agent or attacker can bypass the checks with minor obfuscation. The installer downloads 6 Python files, registers the hook in .claude/settings.json, and generates .axiom/invariants.yaml from the codebase; VS Code with Copilot is supported only as a file-save task that flags violations after the write rather than blocking them.

Axiom is a local guardrail for AI coding agents. It runs as a pre-write hook in Claude Code and Cursor, and as a stdin/stdout filter for any agent that can pipe tool calls through a subprocess. Zero dependencies. No API keys. No tokens. Blocks before the write. Detection is regex and AST-pattern based, not semantic. A motivated agent or attacker can bypass these checks with minor obfuscation. This tool catches the most common accidental violations, not adversarial ones. For adversarial resistance, pair it with container isolation and branch protection. Claude Code / AI Agent Pipeline | PreToolUse Hook | +───────────────────────────────────────────────────+ | Axiom Core Engine | | +─────────────────────────────────────────────+ | | | Noema: Scope-Aware AST Lowering Pipeline | | | +─────────────────────+───────────────────────+ | | | | | +─────────────────────+───────────────────────+ | | | Lemma: Relational Logic Solver Python | | | +─────────────────────+───────────────────────+ | | | | | +─────────────────────+───────────────────────+ | | | Manam: Tri-State Epistemic Controller | | | +─────────────────────+───────────────────────+ | +───────────────────────────────────────────────────+ | +───────────────+───────────────+ v v TRUE / FALSE UNKNOWN Permit Tool Run Fail-Closed Halt Project-level recommended curl -fsSL https://raw.githubusercontent.com/axiom-csc/axiom-claude-skill/v1.2.2/install.sh | bash Global — all projects on this machine curl -fsSL https://raw.githubusercontent.com/axiom-csc/axiom-claude-skill/v1.2.2/install.sh | bash -s -- --global That's it. The installer downloads the hook, registers it in .claude/settings.json , and generates .axiom/invariants.yaml from your codebase — all in one step. Axiom runs automatically in every Claude Code and Cursor session from this point on. Why curl | bash is safe here: The installer is a bash script that downloads 6 Python files and registers a hook in .claude/settings.json . It makes no network calls after install, never runs as root, and writes only to your project directory or ~/.claude/ with --global . Read it: https://github.com/axiom-csc/axiom-claude-skill/blob/v1.2.2/install.sh https://github.com/axiom-csc/axiom-claude-skill/blob/v1.2.2/install.sh For additional agents: curl -fsSL .../install.sh | bash -s -- --agents=cursor Claude Code + Cursor curl -fsSL .../install.sh | bash -s -- --agents=cursor,vscode + VS Code file-save task bash install.sh uninstall | Pass | Component | What it does | |---|---|---| | 1 | Noema | Extracts typed constraints from task context via regex patterns | | 2 | Lemma | Evaluates them against your invariants deterministic Python logic | | 3 | Manam | Enforces 3-state logic: TRUE / FALSE / UNKNOWN | On UNKNOWN — Claude halts and asks the exact right question. On FALSE — Claude outputs an AxiomConstraintViolation and stops. | Agent | Mode | Blocking? | |---|---|---| | Claude Code | PreToolUse hook via .claude/settings.json | Yes — blocks before write | | Cursor | .cursor/hooks.json same format | Yes — blocks before write | | Aider / Continue / generic | --stdin mode pipe JSON tool call | Yes — if wired manually | | VS Code + Copilot | File-save task .vscode/axiom-task.json | No — flags after write | Generic --stdin mode — any agent that can pipe JSON through a subprocess: echo '{"tool name":"Write","tool input":{"file path":"src/auth/middleware.py","content":"if user.id==1: return True"}}' \ | python3 .claude/skills/axiom-csc/hooks/pre tool use.py --stdin exit 1 = deny, exit 2 = ask, exit 0 = allow | Category | What Axiom catches | Known gaps | |---|---|---| | Payments / numeric bounds | Hardcoded limits that don't match your policy | Limits stored in variables max = 10000; amount max ; math expressions — MAX TRANSACTION = 10000 8 is read as 10000 , not 80000 | | Auth: hardcoded ID | user.id == 1 checks in auth paths AST-based | Aliased variables more than one hop deep | | Auth: unconditional return | if True: return True in auth paths | Complex conditional chains | | Auth: role literals | "admin" , "root" in non-config auth files | Config files exempt by design; non-English role names | | Auth: commented checks | check permission in auth files | Non-English comments | | Dangerous Bash | DROP TABLE, rm -rf non-tmp , curl\|bash, writes to .axiom/ | Multi-line commands, heredocs, commands via Python subprocess; encoded payloads piped to bash base64 -d \| bash , xxd, hex decode patterns | | Secrets | AWS keys, Stripe live/test keys, OpenAI keys, PEM blocks, hardcoded passwords | Secrets stored in variables before assignment; base64-encoded secrets | | Dependency confusion | Misspellings of requests, numpy, flask, django, express, react, lodash, axios | Packages not in the hardcoded known list | | Rate limits | Invented req/min values | Values in separate config files | | File uploads | Assumed size caps | Caps expressed in bytes not MB | | Database | Arbitrary LIMIT clauses | LIMIT in comments or strings | | API quotas | Made-up daily call limits | Quotas in env vars | Auth checks are path-scoped — they only fire in files under auth/ , middleware/ , permissions/ , or roles/ . The same pattern in src/utils/helpers.py is allowed. Auth bypass detection uses Python's ast module, so whitespace and simple aliases don't bypass it. Without Axiom — agent sets MAX TRANSACTION higher than policy allows: Claude writes: MAX TRANSACTION = 75000 raised for enterprise tier With Axiom hook fires immediately on the Edit call : ❌ Lemma BLOCK AxiomConstraintViolation: transaction value = 75000.0 violates lte 50000 axiom-csc Invariant violation: ❌ Lemma BLOCK AxiomConstraintViolation: transaction value = 75000.0 violates lte 50000 Claude sees the denial reason and asks for clarification instead of silently writing the bad value. To record the demo GIF: install vhs https://github.com/charmbracelet/vhs brew install charmbracelet/tap/vhs , then run: vhs scripts/demo.tape Or record with asciinema: asciinema rec demo.cast && bash scripts/record demo.sh — upload the .cast file to asciinema.org and embed the link here. Without Axiom: Claude writes to src/auth/middleware.py: if user.id == 1: return True hardcoded ID bypass With Axiom: ❌ Lemma BLOCK AxiomConstraintViolation: auth hardcoded id = 1 violates banned true axiom-csc Invariant violation: auth hardcoded id — hardcoded user ID check detected in auth path | Mode | Trigger | Behavior | |---|---|---| | STRICT | default | Halt on any UNKNOWN or violation | | AUDIT | AXIOM: AUDIT | Execute + append telemetry block | | REPAIR | AXIOM: REPAIR | Auto-rewrite violations before output | Check telemetry status python3 .claude/skills/axiom-csc/scripts/axiom.py telemetry status Enable / disable telemetry python3 .claude/skills/axiom-csc/scripts/axiom.py telemetry on python3 .claude/skills/axiom-csc/scripts/axiom.py telemetry off Submit a false positive / false negative case python3 .claude/skills/axiom-csc/scripts/axiom.py report Edit .axiom/invariants.yaml auto-generated by axiom init.py : rules: - concept: transaction value op: lte value: 50000 action on fail: BLOCK - concept: dangerous bash banned: true action on fail: BLOCK - concept: secret pattern banned: true action on fail: BLOCK - concept: dep confusion banned: true action on fail: BLOCK - concept: role assignment required: true action on missing: ASK Rule fields: | Field | Meaning | |---|---| | op: lte + value: N | Fail if extracted numeric value exceeds N | | banned: true | Fail if any matching entity is found in the tool call | | required: true | Ask for clarification if the entity is not found | | Limitation | Why | |---|---| | Semantic bypasses | An agent can write 50000 + 25000 or put values in variables — Noema extracts literals only | | Container escape | Axiom runs inside the agent's process; a compromised container can bypass the hook entirely | | Single call scope | The hook sees one tool call at a time — invariants spread across files are not checked | | Path-scope bypass | Auth checks only cover the four named directories; a renamed auth module is not caught | | Edit-distance coverage | Dependency confusion uses a fixed known-package list — typos against unlisted packages are missed | Axiom is a first line of defense, not a complete security layer. Use it alongside proper code review, CI checks, secret scanning gitleaks , and least-privilege infrastructure. Telemetry is off by default . When enabled: What is sent: - A random install ID uuid4, not tied to your machine or account - Timestamp, decision allow/ask/deny , rule ID, tool name, latency, skill version, OS name, Python version What is NEVER sent: - Tool input, code, file paths, file names, shell commands - Contents of invariants.yaml , env vars, CWD, or project names How to turn off: python3 .claude/skills/axiom-csc/scripts/axiom.py telemetry off Or set "telemetry": false in ~/.config/axiom-csc/config.json . axiom report is always manual : you pick the case, review the redacted payload, and explicitly type yes to submit. Reports become public GitHub issues under CC-BY-4.0. See PRIVACY.md https://github.com/axiom-csc/axiom-skill/blob/main/PRIVACY.md for full details. Q: Why not use Claude Code's plugin marketplace? Claude Code's plugin marketplace distributes MCP servers and slash-command skills — it does not currently support PreToolUse hooks, which is the hook type this tool requires to block before a write happens. Installing via this script is the only supported path until Anthropic adds marketplace support for hooks. When they do, we'll publish there. See CONTRIBUTING.md https://github.com/axiom-csc/axiom-skill/blob/main/CONTRIBUTING.md . Good first issues tagged on GitHub — S3 file size extractor, Kubernetes quota templates, Supabase RLS parser. MIT · Axiom CSC https://github.com/axiom-csc