AXI — Agent eXperience Interface

The ten design principles behind every tool firstmate uses, the benchmark numbers against MCP and raw CLIs, and how to build your own AXI.

AXI is a specification, not a library. It is "10 design principles for building agent-ergonomic apps" that treat the token budget as a first-class constraint. Home: axi.md, repo kunchenguid/axi.

AXIs are basically CLIs designed specifically for agent ergonomics. as a result, they push token efficiency and task success rate to the extreme. — @kunchenguid, 2026-06-11

AXI's argument is that agents talk to services two ways today, and both cost too much:

• Human CLIs carry verbose output, interactive prompts and ambiguous empties.
• MCP carries eager tool schemas and many round-trips.

An AXI is a CLI whose interface is designed for the model reading it.

Why it matters for firstmate#

Every crewmate brief says: "Use gh-axi for GitHub operations and chrome-devtools-axi for browser operations." Backlog edits go through tasks-axi, and quota decisions through quota-axi. Across a fleet of 10–20 agents, the savings per call compound.

The benchmarks#

Both studies used claude-sonnet-4-6 as the agent with an LLM judge. Sources: axi/bench-browser/published-results/report.md and axi/bench-github/published-results/STUDY.md.

Browser: 490 runs (14 tasks × 7 conditions × 5 repeats)

GitHub: 425 runs (17 tasks × 5 conditions × 5 repeats)

Headline numbers:

• gh-axi vs raw gh: 100% vs 86% success at 7% lower cost.
• gh-axi vs GitHub MCP: 66% cheaper, 74% fewer input tokens, half the turns.

Findings from the original benchmark thread (2026-03-28):

• Claude Code's auto-enabled Tool Search "drops task success rate by 15% compared to raw MCP, without significant cost saving benefit".
• "Code mode" is competitive but 58% slower.
• "Shell pipes give AXI an advantage MCP cannot match": chrome-devtools-axi open <url> 2>&1 | grep -i "designer" navigates and extracts in one command.

The ten principles#

1. Token-efficient output (TOON)#

Emit TOON on stdout. It saves about 40% of tokens versus equivalent JSON. Convert at the output boundary and keep internal logic in JSON.

tasks[2]{id,title,status,assignee}:
  "1",Fix auth bug,open,alice
  "2",Add pagination,closed,bob

2. Minimal default schemas#

Every field costs tokens, multiplied by the row count. Lists default to 3–4 fields (id, title, status). Long content belongs in detail views. Offer --fields for more.

3. Content truncation#

Truncate big fields with a size hint and a --full escape hatch. Don't omit them.

task:
  body: First 500 chars of the issue body...
    ... (truncated, 8432 chars total)
help[1]: Run `tasks view 42 --full` to see complete body

4. Pre-computed aggregates#

"The most expensive token cost is often not a longer response — it's a follow-up call." Include count: 30 of 847 total and checks: 3/3 passed, whatever the backend can compute cheaply.

5. Definitive empty states#

Say tasks: 0 closed tasks found in this repository, not nothing. Ambiguous emptiness makes agents re-run with different flags.

6. Structured errors & exit codes#

• Idempotent mutations: task: #42 already closed (no-op) exits 0.
• Errors on stdout in the same format as the data. No stack traces, and never leak the wrapped tool's name.
• No interactive prompts, ever.
• Fail loud on unknown flags (exit 2): "A dropped flag is worse than an error: the agent gets plausible-looking output it believes is scoped or filtered, then proceeds confidently on wrong data." Fold the subcommand's --help into the error so the agent fixes it in one turn.
• Channels: stdout for everything the agent consumes, stderr for debug. Exit codes: 0 ok (including no-ops), 1 error, 2 usage.

7. Ambient context via session integrations#

Put a compact live dashboard into the agent's context at session start, via hooks installed by an explicit setup command:

• Claude Code: SessionStart in settings.json
• Codex: hooks.json, with [features].hooks = true
• OpenCode: a plugin

Rules for the hook:

• opt-in only,
• idempotent,
• a PATH-verified binary,
• directory-scoped,
• ruthlessly small, because it loads on every session.

Also ship an installable Agent Skill (npx skills add <owner>/<repo> --skill <name>) as a zero-per-session-cost discovery path.

8. Content first#

Running with no arguments shows live state, not a usage manual. "When an agent sees actual state it can act immediately. When it sees help text, it has to make a second call."

9. Contextual disclosure#

After each output, suggest a few relevant, complete, parameterized next commands (<id> placeholders, never guessed values). Omit them when the output is self-contained. Suggest a variety rather than prescribing a sequence. Resolve errors with the specific fixing command, not "see --help".

10. Consistent way to get help#

The home view starts with bin: ~/.local/bin/tasks and a one-line description:. Every subcommand has a concise --help (flags, defaults, 2–3 examples).

The --version fast path: -v, -V and --version print the bare version and exit fast, because harnesses probe versions constantly. The named trap is an ESM static import that pulls the whole command graph in before the version check. The fix keeps VERSION in a leaf module:

#!/usr/bin/env node
import { tryFastPath } from "axi-sdk-js/fast-path";
import { VERSION } from "../src/version.js"; // leaf module - node builtins only
if (!tryFastPath(process.argv.slice(2), { version: VERSION })) {
  const { main } = await import("../src/cli.js"); // heavy graph loads only here
  await main();
}

Build your own AXI#

npx skills add kunchenguid/axi

That installs the full principle guide (.agents/skills/axi/SKILL.md) for your coding agent to follow while building. The JS SDK, axi-sdk-js, provides runAxiCli (dispatch, validation, error formatting, exit codes) and the zero-import axi-sdk-js/fast-path. Its scope is kept narrow on purpose.

The recommended integration order:

1. a setup hooks command for ambient context,
2. an installable skill as the lighter secondary path.

The community catalog (axi/catalog.yaml) lists about 85 AXIs: Slack, Jira, Linear, Postgres, Kubernetes, Figma, Cloudflare and more. Admission requires independent source review at a pinned revision, and deviations are recorded as explicit exceptions. axi-axi (community) scaffolds and compliance-checks a candidate CLI.