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.

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.

License

Apache-2.0