axi-axi

An AXI (Agent eXperience Interface) for AXI — a token-efficient CLI for AI agents to create new AXIs.

AXI is a set of 10 design principles for building agent-ergonomic CLIs. axi-axi is the meta-tool: instead of loading the whole spec into its context window, an agent building a new AXI runs axi-axi to get just-in-time slices of the spec, a compliant project scaffold, and automated compliance validation. axi-axi follows all 10 principles itself — CI includes a self-validation gate.

Installation

axi-axi is published to npm as a self-contained CLI (zero runtime dependencies). It requires Node.js 20 or newer.

Run once, no install (recommended)

The fastest way to use axi-axi — and the intended path for AI agents — is npx, which fetches and runs the latest version without installing anything:

npx -y axi-axi                    # home view: the 10 principles + golden path
npx -y axi-axi new my-tool        # scaffold a new AXI project

The -y flag skips npx's install prompt, keeping it non-interactive for agents and CI.

Install globally

If you reach for axi-axi often and want an axi-axi command on your PATH:

npm install -g axi-axi
axi-axi                           # run it directly
axi-axi --version                 # print tool + spec version

Upgrade with npm install -g axi-axi@latest; remove with npm uninstall -g axi-axi.

Add to a project

To pin axi-axi as a dev dependency of a repository — e.g. to run compliance checks in CI:

npm install --save-dev axi-axi
npx axi-axi validate "node ./bin/my-tool.js"   # resolves the local install

Other package managers

axi-axi is a plain npm package, so the usual equivalents work:

Tool	Run once	Install globally
npm	npx -y axi-axi	npm install -g axi-axi
pnpm	pnpm dlx axi-axi	pnpm add -g axi-axi
yarn	yarn dlx axi-axi	yarn global add axi-axi
bun	bunx axi-axi	bun add -g axi-axi

For agents

npx -y axi-axi                          # home view: the 10 principles + golden path
npx -y axi-axi new my-tool --dir ./my-tool
npx -y axi-axi checklist --phase implement
npx -y axi-axi principles show errors-exits
npx -y axi-axi validate "node ./my-tool/bin/my-tool.js" --dir ./my-tool

Two integration paths (both optional):

• Session hook (ambient, live): npx -y axi-axi setup hooks installs a SessionStart hook loading the home view at session start (Claude Code and Codex; explicit opt-in, idempotent, removable with --remove).
• Skill (on-demand): skills/axi-axi/SKILL.md is generated from the same content as the home view; CI keeps it fresh.

Commands

Command	What it does
axi-axi	Content-first home view: principle index + golden path
axi-axi principles list / show <id>	The 10 principles, served in token-tuned slices
axi-axi checklist [--phase] [--principle]	~36 actionable items across design/implement/ship
axi-axi checks list	Catalog of the validator's checks (know the bar up front)
axi-axi new <name> [--dir]	Scaffold a compliant AXI project (zero runtime deps)
axi-axi validate "<cmd>" [--dir]	Read-only compliance probes: pass/fail/warn + advisory
axi-axi skill gen [--check]	Generate/verify SKILL.md from the home view content
axi-axi setup hooks [--remove]	Install/remove the SessionStart session hook

Every command supports --help. Exit codes: 0 success/no-op, 1 error, 2 usage error. All agent-consumed output is TOON on stdout.

Develop

npm install
npm run build      # also syncs shared helpers into the scaffold templates
npm test           # unit + e2e (includes the self-validation gate)

Design notes:

• Zero runtime dependencies. The strict flag parser, TOON emitter, and error rendering are small hand-rolled modules in src/cli/ and src/output/ — swapping them for the upstream axi-sdk-js later is a contained refactor of those two directories.
• Scaffold can't drift. templates/project/src/{cli,output}/ are byte-identical copies of axi-axi's own modules, synced by scripts/sync-templates.mjs (prebuild) and checked in CI.
• The embedded spec lives in src/spec/data.ts (snapshot axi/1.0-2026-07), with unit-enforced token budgets per principle.

Releasing

Publishing is automated: .github/workflows/publish.yml runs on every push to main and publishes to npm only when package.json carries a version the registry doesn't have yet. To cut a release:

npm version patch   # or minor / major — bumps package.json and commits

Merge that bump into main and CI does the rest (prepublishOnly rebuilds and runs the full test suite, including the self-validation gate, before upload).

Auth uses npm trusted publishing (OIDC) — no token secret. The trusted publisher is configured on npmjs.com (package Settings → Trusted Publisher): GitHub Actions, user CodyEngel, repository axi-axi, workflow filename publish.yml, no environment. If the workflow file is ever renamed, update that config to match.

License

Apache-2.0