Status: Experimental CLI prototype and concept specification
Purpose: Generate deterministic guardrails for AI-assisted applications from readable capability contracts.

Axiom is an experimental CLI and language concept for building AI-assisted software where sensitive actions are checked by generated code, not by model obedience.

The repo now includes a first usable MVP: a dependency-light Node CLI that parses .ax files, validates capability contracts, reports permission and disclosure problems, simulates allow/deny/approval decisions, and generates TypeScript and Python policy artifacts, route gates, approval checks, audit contracts, runtime guards, and tests.

Axiom itself does not connect to an LLM or spend model tokens. Token cost only appears when a human or coding agent chooses to put Axiom content into model context. The intended workflow is compact local commands, targeted simulations, diffs, generated tests, and short summaries instead of pasting full contracts, reports, or generated files into chat.

Current Status

Axiom OS is public now as an experimental developer tool. The CLI, examples, and docs are usable from a checkout while packaging and the npm release path are hardened.

The package is intentionally still marked "private": true. Packaging work in this repo is for dry runs and local install testing until npm publication is intentional.

Start Here

Prerequisite: Node.js 20 or newer.

The open-source flow is designed for a human who installs Axiom and an AI coding agent that works inside a project, with generated checks available for ordinary app code to enforce.

For the shortest local try:

git clone https://github.com/Tranz007/Axiom.git
cd Axiom
node ./bin/axiom.mjs try --out /tmp/axiom-starter

That creates a starter project, runs doctor, runs starter simulations, and prints the next useful command for the agent.

To describe or update the rules Axiom should follow:

node ./bin/axiom.mjs define --guided --cwd /tmp/axiom-starter

That writes axiom/contract-outline.md, a plain-language worksheet the human and coding agent can use to create or update app.ax.

For a guided template picker:

node ./bin/axiom.mjs init --guided --out /tmp/axiom-starter

For the direct path:

git clone https://github.com/Tranz007/Axiom.git
cd Axiom
node ./bin/axiom.mjs init --template local-private-app --agent codex --out /tmp/axiom-starter
node ./bin/axiom.mjs doctor --cwd /tmp/axiom-starter
node ./bin/axiom.mjs next --cwd /tmp/axiom-starter
node ./bin/axiom.mjs simulate-examples --cwd /tmp/axiom-starter
node ./bin/axiom.mjs next --cwd /tmp/axiom-starter
node ./bin/axiom.mjs generate /tmp/axiom-starter/app.ax --target typescript --out /tmp/axiom-starter/generated
node ./bin/axiom.mjs verify /tmp/axiom-starter/app.ax --target typescript --out /tmp/axiom-starter/generated --write
node ./bin/axiom.mjs generate-tests /tmp/axiom-starter/app.ax --examples /tmp/axiom-starter/axiom/simulations.json --out /tmp/axiom-starter/generated-tests
node --test /tmp/axiom-starter/generated-tests/axiom-policy.test.mjs

That creates:

• app.ax: the app contract
• AGENTS.md: instructions for the coding agent
• axiom/simulations.json: starter policy scenarios
• axiom/simulation-results.json: saved simulation output after simulate-examples
• generated/: TypeScript policy and contract artifacts after generate
• axiom/verification-manifest.json: graph and generated artifact hashes after verify --write
• axiom/verification-report.md: compact verification report after verify --write
• generated-tests/: runnable Node policy tests after generate-tests

To inspect the bundled examples:

node ./bin/axiom.mjs validate examples/agent-capability-gateway/axiom.ax
node ./bin/axiom.mjs validate examples/customer-support-action/axiom.ax
node ./bin/axiom.mjs matrix examples/agent-capability-gateway/axiom.ax
node ./bin/axiom.mjs diff examples/local-private-notes/axiom.ax templates/apps/local-private-app.ax
node ./bin/axiom.mjs simulate examples/agent-capability-gateway/axiom.ax --capability fill_tax_identity_fields --fact standing_policy_absent=true
node ./bin/axiom.mjs simulate examples/customer-support-action/axiom.ax --capability issue_refund_credit --fact refund_requested=true
node ./bin/axiom.mjs generate examples/agent-capability-gateway/axiom.ax --target typescript --out examples/agent-capability-gateway/generated
node ./bin/axiom.mjs verify examples/agent-capability-gateway/axiom.ax --target typescript --out examples/agent-capability-gateway/generated
node --test examples/customer-support-action/generated/app-skeleton.test.mjs
node --test examples/customer-support-action/generated/route-skeleton.test.mjs
node --test examples/customer-support-action/generated/approval-ui.test.mjs
node --test examples/customer-support-action/generated/integration-contracts.test.mjs
node ./bin/axiom.mjs generate templates/apps/local-private-app.ax --target python --out /tmp/axiom-python-generated
node examples/customer-support-action/app/policy-demo.mjs
node examples/customer-support-action/app/support-mini-app.mjs
node examples/local-private-notes/app/policy-demo.mjs
python3 examples/local-private-notes-python/app/policy_demo.py
node --test

If npm is available, these shortcuts also work:

npm run validate:examples
npm run generate:example
npm run demo:local-private-notes
npm run demo:local-private-notes-python
npm test

For local tool testing from a checkout:

npm link
axiom init --guided --out /tmp/axiom-linked-starter
axiom doctor --cwd /tmp/axiom-linked-starter

To inspect what would be included in a package without publishing:

npm pack --dry-run

What Works Today

The current CLI can:

• initialize starter app.ax projects with AI coding agent instructions
• guide first-time setup with axiom init --guided
• inspect project readiness with axiom doctor
• recommend the next useful agent action with axiom next, including generation, verification, generated tests, stale artifacts, and compact policy test runs
• run starter policy simulations with axiom simulate-examples
• run a complete two-minute local walkthrough with axiom try
• create a plain-language contract worksheet with axiom define
• generate runnable policy tests from starter simulations with axiom generate-tests
• verify generated artifacts against app.ax with graph and artifact hashes using axiom verify
• parse the MVP indentation-based .ax format
• validate that capabilities declare purpose, policy, disclosure, broker, approval, and audit obligations where required
• explain common sensitive-data validation failures with concrete next steps
• fail unsafe examples such as raw sensitive export, missing approval paths, model-decided policy, and unsafe audit logging
• print a policy matrix as JSON
• diff two .ax contracts for capability and data-class changes
• simulate deterministic policy decisions from boolean request facts
• generate TypeScript artifacts for capabilities, data classes, broker boundaries, approval payloads, audit guards, runtime guards, and generation reports
• generate a minimal Node app skeleton that gates policy, approval, broker, and audit behavior
• generate framework-neutral route skeletons with manual auth, broker, audit, persistence, and transport hooks
• generate approval review models that expose required binding fields before a human approves
• generate explicit manual integration contracts for auth, broker, audit, approval persistence, and transport adapters
• run a tiny customer-support mini app that proves approval review, approved broker execution, failure-before-broker paths, audit capture, and one HTTP-shaped route adapter
• write verification manifests with generated test artifact coverage metadata
• generate Python artifacts for Pydantic contract models, deterministic policy evaluation, audit obligation stubs, and generation reports
• run tiny Node and Python examples that import generated policy evaluators from ordinary app code

The current CLI cannot yet:

• generate a full application
• replace framework code
• execute policies against real request context
• generate polished UI screens or complete production persistence/auth layers
• parse rich expressions beyond simple boolean facts
• guarantee security by itself
• parse every future Axiom syntax idea in the docs

In ordinary development, a human or agent writes framework code first: React components, API routes, database models, middleware, tests, deployment config. Security and intent are scattered across comments, docs, auth checks, policy files, test suites, and memory.

Axiom changes that order.

The contract becomes an executable enforcement graph:

• what the system is for
• what actors may request
• what data classes exist
• what capabilities are allowed
• what effects are dangerous
• what policy decides
• when approval is required
• what the broker may disclose
• what must be audited
• what invariants must never be violated

Axiom should eventually compile that graph into ordinary software artifacts: TypeScript, Python, FastAPI routes, React UI, policy rules, tests, audit schemas, deployment manifests, and runtime guards. Today, this repo implements the smaller open-source core: contract validation, policy simulation, TypeScript and Python policy artifacts, generated policy tests, generated Node route/approval/integration contracts, and runnable examples.

The goal is not prettier syntax or longer prompts. The goal is to put sensitive actions behind deterministic checks the model does not control.

Editions

• Axiom OS: the open-source local core in this repo.
• Axiom Enterprise: future commercial tooling for teams, managed workflows, stronger reports, and organizational governance.
• Axiom Government: future private/government-focused edition for stricter deployment, audit, and compliance environments.

The open-source version needs to be useful by itself. The future editions should add operational depth, not make the public core a teaser.

One-Sentence Definition

Axiom turns readable capability contracts into generated policy evaluators, approval gates, broker guards, audit contracts, runtime checks, and tests for ordinary application code.

The Core Bet

AI agents should not be trusted because they are authenticated, useful, convincing, or locally running in a developer tool.

They should be able to act only through narrow, declared, policy-checked capabilities, and the policy decision should happen outside the model.

Axiom makes this pattern native.

What Axiom Is

Axiom is:

• a readable contract layer above normal application frameworks
• a capability definition language
• a policy and approval contract language
• a threat-model-aware compiler
• a generator for runtime enforcement artifacts
• a semantic audit generator
• a way to keep AI-assisted software from silently expanding its own authority

What Axiom Is Not

Axiom is not:

• JSON with nicer names
• YAML config for agents
• a replacement for browsers, servers, or databases
• a general-purpose scripting language
• a magical zero-day shield
• a reason to skip ordinary security engineering
• a way to make LLMs obey prompts
• a way for models to decide policy
• a broad memory or secret retrieval interface
• a framework that should be used for every small website

Why It Exists

Human-first programming languages were designed around instructions:

do this
then this
call that
return this

Agent-built systems need a deeper contract:

this is the purpose
this is the actor
this is the authority
this is the sensitive data involved
this is the destination
this is the allowed disclosure
this requires approval
this is forbidden
this must be audited
this must stop if the world changes

Axiom exists because software built by agents needs to preserve intent and authority as first-class executable structure.

The Shape Of An Axiom Program

An Axiom application is made from:

• Worlds: bounded operating contexts
• Actors: users, agents, services, workers, admins
• Data Classes: typed sensitive or operational data
• Capabilities: narrow operations that actors can request
• Policies: deterministic allow / deny / require_approval decisions
• Brokers: trusted execution boundaries that may touch sensitive data
• Effects: external or irreversible actions
• Approvals: scoped human authorization gates
• Invariants: promises the system must keep
• Audit Events: durable semantic traces of sensitive operations
• Targets: generated code and deployment artifacts

See docs/language-overview.md for details.

Why This Complexity Exists

Human developers should be skeptical of new layers.

Axiom should not be used just because it is conceptually interesting. It is useful only when the system already has cross-cutting authority complexity: agents, sensitive data, approvals, external effects, audit obligations, and policy decisions that must not depend on model judgment.

The point is not to add ceremony. The point is to move security-critical promises out of scattered code, comments, and tribal memory into executable structure.

See docs/why-axiom.md.

Initial Documentation Map

• spec/grammar.md: MVP grammar currently supported by the CLI
• docs/language-overview.md: core concepts and syntax
• docs/runtime-model.md: build-time, runtime, frontend, backend, deployment
• docs/security-model.md: security posture, threats, capability isolation
• docs/token-budget.md: why Axiom itself does not spend LLM tokens, plus context-budget constraints for agent use
• docs/first-agent-loop.md: compact golden path for agent use
• docs/setting-axiom-rules.md: how users create and update the contract
• docs/setting-axiom-rules.html: public-facing page for setting the contract
• docs/risks.html: plain-language page explaining agent failure modes and where Axiom helps
• docs/compiler-and-targets.md: how Axiom compiles to real software
• docs/axiom-os.html: public-facing open-source edition page
• docs/editions.html: public-facing edition strategy page
• docs/editions.md: Axiom OS, Axiom Enterprise, and Axiom Government distribution strategy
• docs/agent-instructions.md: instructions layer for AI coding agents and non-expert builders
• docs/why-axiom.html: developer-facing rationale for the added layer
• docs/skills-vs-axiom.html: how Axiom differs from Markdown agent skills and reusable AI guidance
• docs/why-axiom.md: plain Markdown source for the rationale
• docs/comparison-matrix.html: human-readable visual comparison matrix
• docs/comparison-matrix.md: plain Markdown source for the comparison matrix
• docs/roadmap.md: phased implementation plan
• docs/open-source-readiness.md: current release readiness status
• docs/release-checklist.md: public repository and npm release checklist
• BACKLOG.md: tactical next work for open-source readiness
• CHANGELOG.md: notable repo changes
• CONTRIBUTING.md: contribution priorities and local checks
• SECURITY.md: prototype security posture and reporting guidance
• CODE_OF_CONDUCT.md: project conduct expectations
• TRADEMARKS.md: project name and brand-use guidance
• examples/receipt-archive.ax: small app example
• examples/receipt-archive: runnable receipt archive example with generated artifacts
• examples/customer-support-action: support reply and approval-gated refund example
• examples/local-private-notes: tiny runnable app example that imports a generated policy evaluator
• examples/local-private-notes-python: tiny runnable Python example that imports a generated policy evaluator
• examples/agent-capabilities.ax: generic agent capability gateway example
• examples/agent-capability-gateway: runnable agent gateway example with generated artifacts
• tests/fixtures/bad: intentionally unsafe examples that should fail validation