axi

Agent eXperience Interface (AXI)

AXI defines ergonomic standards for building CLI tools that autonomous agents interact with through shell execution.

Before you start

Read the TOON specification before building any AXI output.

1. Token-efficient output

Use TOON (Token-Oriented Object Notation) as the output format on stdout. TOON provides ~40% token savings over equivalent JSON while remaining readable by agents. Convert to TOON at the output boundary — keep internal logic on JSON.

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

2. Minimal default schemas

Every field in stdout costs tokens — multiplied by row count in collections. Default to the smallest schema that lets the agent decide what to do next: typically an identifier, a title, and a status.

• Default list schemas: 3-4 fields, not 10
• Default limits: high enough to cover common cases in one call (if most repos have <100 labels, default to 100, not 30)
• Long-form content (bodies, descriptions) belongs in detail views, not lists
• Offer a --fields flag to let agents request additional fields explicitly

3. Content truncation

Detail views often contain large text fields. Omitting them forces agents to hunt; including them wastes tokens. Truncate by default and tell the agent how to get the full version.

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

• Never omit large fields entirely — include a truncated preview
• Show the total size so the agent knows how much it's missing
• Suggest the escape hatch (--full) only when content is actually truncated
• Choose a truncation limit that covers most use cases (500-1500 chars)

4. Pre-computed aggregates

The most expensive token cost is often not a longer response — it's a follow-up call. If your backend has data that agents commonly need as a next step, compute it and include it.