Agent eXperience Interface (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