Skip to content

Latest commit

 

History

159 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AXI: Agent eXperience Interface

Website X Discord

10 design principles for building agent-ergonomic apps.

AXI — Let's build apps agents love.

AI agents interact with external services through two dominant paradigms today: CLIs which were originally built for humans, and structured tool protocols like MCP. Both impose significant overhead.

AXI is a new paradigm - agent-native CLI tools built from 10 design principles that treat token budget as a first-class constraint.

Results

Browser Benchmark

Evaluated across 490 runs (14 tasks × 7 conditions × 5 repeats) using Claude Sonnet 4.6:

Condition Success Avg Cost Avg Duration Avg Turns
chrome-devtools-axi 100% $0.074 21.5s 4.5
dev-browser 99% $0.078 28.6s 4.9
agent-browser 99% $0.088 24.6s 4.8
chrome-devtools-mcp-compressed 100% $0.091 29.7s 7.6
chrome-devtools-mcp-search 99% $0.096 29.4s 7.5
chrome-devtools-mcp 99% $0.101 26.0s 6.2
chrome-devtools-mcp-code 100% $0.120 36.2s 6.4

GitHub Benchmark

Evaluated across 425 runs (17 tasks × 5 conditions × 5 repeats) using Claude Sonnet 4.6:

Condition Success Avg Cost Avg Duration Avg Turns
gh-axi 100% $0.050 15.7s 3
gh (CLI) 86% $0.054 17.4s 3
GitHub MCP 87% $0.148 34.2s 6
GitHub MCP + ToolSearch 82% $0.147 41.1s 8
MCP + Code Mode 84% $0.101 43.4s 7

Claude Sonnet 4.6 is the model the published runs used, not a limit of the harness. Both benchmarks take --model, which is passed straight through to the agent CLI, so any Claude model works - for example --model claude-opus-4-6. Results for other models are simply not published here, and they may respond differently to output format.

Quick Start

Reference AXI implementations:

See the full AXI Catalog below for all official and community AXIs.

npm install -g gh-axi
npm install -g chrome-devtools-axi

Add to your CLAUDE.md or AGENTS.md:

Use `gh-axi` for GitHub and `chrome-devtools-axi` for browser automation.

The 10 Principles

These principles define what makes a CLI tool "an AXI". The table below is generated from principles.yaml; the full specification of each principle lives in the AXI skill.

# Principle Summary
1 Token-efficient output Use TOON format for ~40% token savings over JSON
2 Minimal default schemas 3–4 fields per list item, not 10+
3 Content truncation Truncate large text with size hints and a --full escape hatch
4 Pre-computed aggregates Include aggregated counts and statuses that eliminate round trips
5 Definitive empty states Explicit "0 results" rather than ambiguous empty output
6 Structured errors & exit codes Idempotent mutations, structured errors, no interactive prompts, fail loud on unknown flags
7 Ambient context Install opt-in session integrations first, then offer an on-demand skill
8 Content first Running with no arguments shows live data, not help text
9 Contextual disclosure Include next-step suggestions after each output
10 Consistent way to get help Concise per-subcommand reference when agents need it

AXI Catalog

The catalog tables below are generated from catalog.yaml - see CONTRIBUTING.md to add your AXI.

Official

Reference implementations maintained by the AXI project, validating the principles across different domains:

AXI Domain What it does
gh-axi GitHub Issues, PRs, workflow runs, releases, and more. Wraps the official gh CLI with agent-ergonomic output.
chrome-devtools-axi Browser automation Navigate, click, fill, and extract with combined operations and query filtering. Wraps chrome-devtools-mcp.
lavish-axi Human review Turns agent-generated HTML artifacts into collaborative review surfaces - annotate, comment, and send feedback back to the agent.
quota-axi Quota / usage Reports local Claude, Codex, Cursor, Copilot, and Grok quota/usage windows for routing-aware agents - data-only and local-first.

Community

AXIs built and maintained by the community:

AXI Author Domain What it does
jj-axi aivv73 Version control Inspect and reshape Jujutsu history through deterministic, non-interactive commands with compact TOON output and operation-aware undo.
npm-axi SSBrouhard npm Search and inspect npm registry packages, versions, dependencies, README previews, and downloads with token-efficient output.
sqlite-axi SSBrouhard SQLite Inspect schemas, sample rows, and run capped read-only SQLite queries with token-efficient TOON output.
slack-axi Jarvus Innovations Slack Read, search, sweep, and safely draft Slack messages with token-efficient output.
gws-axi Jarvus Innovations Google Workspace Gmail, Calendar, Docs, Drive, and Slides behind one command, with multi-account write-safety - drafts mail, never sends.
harvest-axi Jarvus Innovations Time tracking Review, log, and edit Harvest time entries by period - for yourself, your team, a project, or a client.
specops Jarvus Innovations Spec-driven dev Spec-driven development for agents - and a demo of shipping an AXI embedded in a skill, not a standalone npm executable.
gitsheets-axi Jarvus Innovations Git-backed data Read and mutate git-backed record sheets over the shell - TOON output, idempotent commits.
metabase-axi Jarvus Innovations Analytics / BI Query, explore, and export from Metabase over the shell - SQL/MBQL, saved questions, schema introspection, full-data export.
otter-axi Jarvus Innovations Meetings Find and pull Otter.ai meeting transcripts from the shell - wraps Otter.ai's hosted MCP server as a scriptable, headless CLI.
notion-axi maximebrmd Notion Search, read, create, and update Notion pages and databases over the shell - token-efficient TOON output, PAT or integration auth.
clickup-axi JanSuthacheeva ClickUp List your open tasks, view a task with its newest comments inline, and change task status - truncation-aware, TOON-style output.
databricks-axi p33ves Databricks Run Databricks jobs, watch runs, and pull failure logs inline over the official databricks CLI - more domains coming soon.
aws-axi thatdudealso AWS Discover, plan, provision, deploy, and inspect AWS services for hosting web, backend, database, and AI workloads through safe token-efficient CLI workflows.
docker-axi thatdudealso Docker Discover, build, run, debug, publish, inspect, and clean up Docker apps through safe token-efficient CLI workflows.
doctl-axi batamire DigitalOcean Manage Droplets, Kubernetes, App Platform, databases, networking, and Spaces via doctl with token-efficient TOON output.
dynamodb-axi thatdudealso DynamoDB Discover, inspect, query, scan, create, update, back up, restore, export, import, and safely operate DynamoDB tables through token-efficient CLI workflows.
pg-axi thatdudealso PostgreSQL Discover, create, inspect, query, back up, restore, and maintain PostgreSQL databases through safe token-efficient CLI workflows.
mongodb-axi thatdudealso MongoDB Discover, create, inspect, query, export, import, maintain, and diagnose MongoDB databases through safe token-efficient CLI workflows.
elasticsearch-axi thatdudealso Elasticsearch Discover, inspect, query, index, map, snapshot, restore, diagnose, and operate Elasticsearch clusters through safe token-efficient CLI workflows.
kubernetes-axi thatdudealso Kubernetes Discover, inspect, deploy, debug, scale, roll out, expose, and clean up Kubernetes workloads through safe token-efficient CLI workflows.
redis-axi thatdudealso Redis Discover, inspect, query, export, import, maintain, and diagnose Redis databases through safe token-efficient CLI workflows.
celery-axi thatdudealso Celery Discover, inspect, run, debug, monitor, schedule, control, and safely operate Celery task queues through token-efficient CLI workflows.
cyber-mux unional Terminal multiplexers Open, send, read, focus, and close terminal panes across tmux, herdr, and WezTerm through one detection-driven contract with token-efficient output.
oracle-axi thatdudealso Oracle Database Discover, create, inspect, query, export, import, maintain, and diagnose Oracle databases through safe token-efficient CLI workflows.
glab-axi karotkriss GitLab Issues, merge requests, CI/CD pipelines, variables and secrets, releases, and raw API access. Wraps the official glab CLI with agent-ergonomic TOON output.
reactive-axi adeeshsharma UI review Click any element in your live React, Vue, or Svelte dev server and resolve it to the exact source file and line before it reaches your agent.
obsidian-axi AndersHoffmann Obsidian Read, search, create, update, organize, and link Obsidian notes from the filesystem - compact TOON output, atomic writes, no plugin or server.
comfy-cloud-axi intelligentrascal AI generation Generate images, video, and audio via 22 partner models, submit ComfyUI workflows and templates, track jobs, estimate credits before generating, search nodes, and report usage — wraps the Comfy Cloud MCP server with token-efficient TOON output.
mobbin-axi intelligentrascal UI/UX research Search real-world UI/UX patterns from production apps via Mobbin - wraps Mobbin's OAuth-gated MCP server as a scriptable, headless CLI with token-efficient TOON output.
calendly-axi Jarvus Innovations Scheduling The Calendly booking loop from the shell - see what's scheduled, mint single-use booking links, book directly, cancel, and manage event types, availability, and webhooks.
remarkable-axi Jarvus Innovations E-ink tablets Manage content on your reMarkable tablet through the reMarkable cloud - browse and organize files, upload PDFs and EPUBs, and send web articles as reflowable EPUBs.
ado-axi dtabolich Azure DevOps Pull requests, branches, repositories, and pipeline runs. Wraps Azure CLI (az devops / az repos) with agent-ergonomic TOON output.
ado-axi jeffreyhaen Azure DevOps Work items, pull requests, Git refs, pipelines, and raw Azure DevOps REST calls with safe mutations, profiles, and token-efficient TOON output.
supabase-axi laizhenyoong Supabase Inspect schemas, run SQL, and audit RLS, indexes, and logs across Supabase projects. Wraps the Supabase Management API.
homebrew-axi mstuart Homebrew Inspect Homebrew formulae, casks, and installed packages — versions, dependencies, outdated status, and install stats — with token-efficient TOON output; read-only, never mutates.
pypi-axi mstuart PyPI Inspect PyPI packages, versions, dependencies, and download stats with token-efficient TOON output — read-only, no auth required.
cargo-axi AG9898 Rust / Cargo Inspect Rust workspaces and run safe check or Clippy validation with compact TOON output and opt-in session context.
forgejo-axi escidmore Forgejo Pull request lifecycle, issues, and raw API access for self-hosted Forgejo - non-interactive, reconciling mutations, with token-efficient TOON output.
mastra-axi taltas Mastra Discover and run a Mastra app's agents, tools, and workflows through agent-native shell commands with compact TOON output.
axi-axi CodyEngel AXI authoring Scaffold a compliant AXI, read the 10 principles in token-tuned slices, and run read-only compliance checks against a candidate CLI.
jira-axi emilchristensen Issue tracking Create, search, transition, and comment on Jira work items, boards, and sprints through Atlassian's acli with token-efficient TOON output and idempotent mutations.
confluence-axi emilchristensen Documentation Read and write Confluence Cloud pages and spaces directly over the REST API with token-efficient TOON output and OAuth 3LO or API-token auth.
az-axi masyanru Azure Discover, inspect, query, and safely mutate Azure through token-efficient CLI workflows over every az module.
mssql-axi jeffreyhaen Microsoft SQL Server / Azure SQL Inspect schemas, sample rows, run capped read-only queries and showplans over the native ODBC driver - mutations double-gated with dry-run by default, TOON output.
superbee Holaxis Agent knowledge infrastructure Turns what agents know into durable, domain-shaped infrastructure through local OKF bundles with declared schemas, exact queries, conflict-safe writes, and portable Views.
figma-axi ardaatahan Design / Figma Inspect Figma files, export nodes to PNG/SVG/PDF, and read styles, components, and comments - summarizes huge files instead of dumping raw JSON.
trello-axi enzodevs Project management Create, search, update, move, comment on, and archive Trello cards through the REST API with compact TOON output, complete pagination, idempotent mutations, and non-interactive batch workflows.
railway-axi simkimsia Railway List projects and inspect linked project status, environments, and services. Wraps the Railway CLI with agent-ergonomic TOON output and structured errors.
netlify-axi simkimsia Netlify List sites and inspect the linked site's status and the logged-in account. Wraps the Netlify CLI with agent-ergonomic TOON output and structured errors.
vercel-axi ardaatahan Deployment / Vercel Deploy and inspect Vercel deployments, projects, domains, DNS, environment variables, and teams through the official Vercel CLI, with explicit confirmation gates for production and infrastructure changes.
cloudflare-axi simkimsia Cloudflare Inspect the current Worker's deployments, Pages projects, KV namespaces, and the logged-in account. Wraps the Cloudflare CLI (wrangler) with agent-ergonomic TOON output and structured errors.
coolify-axi radityasurya Coolify Apps, databases, services, and deployments on self-hosted or cloud Coolify - name-based addressing, redacted secrets, and TOON output over the official coolify CLI.
porkbun-axi ardaatahan Domains / Porkbun Manage Porkbun domains, DNS records, SSL certificates, URL forwarding, nameservers, and glue records through the Porkbun API, with compact TOON output and explicit confirmation gates for registrations and destructive updates/deletes.
wrangler-axi masculinecache Cloudflare Wrangler Deploy Workers and Pages, manage KV namespaces, D1 databases, R2 buckets, and Worker secrets, and tail live logs with hard bounds - wraps the official Wrangler CLI with predictable TOON lists and structured errors.
chezmoi-axi masculinecache Dotfiles List, diff, add, re-add, apply, verify, and sync chezmoi-managed dotfiles with compact TOON output - template-aware re-add verdicts, preview dry-runs, and idempotent operations.
mem-axi masculinecache Agent memory Durable cross-session agent memory as markdown + YAML frontmatter in a git repo - typed memories, priority-ranked search with L0 abstracts, OS-side dedup, and cross-machine sync.
fal-axi ardaatahan Image / Video Generation Generate images and videos and poll fal.ai queue status/results through the official @fal-ai/client, with compact TOON output, FAL_KEY env-only auth, and --confirm gates on paid generates.
canva-axi ardaatahan Design / Canva List, get, create, export, and autofill Canva designs through the official Canva Connect API, with compact TOON output, CANVA_ACCESS_TOKEN env-only auth, HTTPS-only API bases, and --confirm gates on mutating writes.
bws-axi masculinecache Bitwarden Secrets Manager Agent-ergonomic Bitwarden Secrets Manager CLI - TOON output, values redacted by default, project/key scoped listings.
ha-axi batamire Home Assistant Inspect entities, call services behind safety gates, render templates, and read area/device registries over Home Assistant REST and WebSocket with token-efficient TOON output.
calcom-axi simkimsia Scheduling Read your Cal.com agenda, bookings and one booking's attendees and meeting link, event types, availability schedules, free slots for an event type, and the logged-in account. Wraps the Cal.com CLI (calcom) with agent-ergonomic TOON output and structured errors.
screencast-axi Valzon Screencasts Scaffold, rehearse, and record scripted Playwright walkthroughs of any website into mp4, webm, and a poster with a synthetic cursor and burnt-in captions - TOON output, structured errors, and a content-first status view via axi-sdk-js. Requires ffmpeg.
basecamp-axi calebl Project management Projects, to-dos, cards, messages, comments, Campfire chat, people, search, and cross-project assignment reports. Wraps the official basecamp CLI with TOON output, pre-computed totals, idempotent mutations, and a --confirm gate on trash/archive/restore.
msgraph-axi jeffreyhaen Microsoft 365 / Outlook Read, search, draft, and send Outlook mail and manage calendars over the m365 CLI - read-only by default, with TOON output and mutations behind --execute/--confirm.
frontier-axi oguzalp7 Pre-flight SDLC & Cognitive Bridge Stage ambiguous ideas and architectural inquiries until grilling settles them into tasks-axi tickets with token-efficient TOON output.
design-system-axi isamrish Design systems Look up components, import paths, props, and examples from a design system's Storybook manifest and metadata, with a deterministic find that marks weak matches - Primer React first.
shopify-axi elliottkan Shopify Search shopify.dev and validate generated GraphQL, Liquid themes, and Polaris components against the real schemas - wraps Shopify's Dev MCP server and exits non-zero on hallucinated fields.
asana-axi elliottkan Project management Create, search, update, and comment on Asana tasks, projects, and portfolios through Asana's official V2 MCP server as a scriptable headless CLI, with OAuth login, TOON output, and structured errors.
clockify-axi elliottkan Time tracking Wraps Clockify's full REST API (not just its 13-tool MCP server) with a cached workspace/user identity, TOON output, and AXI exit codes for timers, time entries, projects, tasks, clients, tags, and reports.
jev-axi shiftynick AI judgments Offload snap judgments to TypeSafe's Jev model - pick, rate, check, rank, filter, semantic grep, diff review, log triage, and prompt-injection screening over files or stdin, with calibrated confidence bands and local usage/cost stats.
linear-sdk-axi shiftynick Linear Issues, comments, relations, projects, project updates, cycles, labels, and teams over the official @linear/sdk - no MCP server, with dry-run, verified writes, bounded pagination, and TOON or JSON output.
asana-axi brycehamrick Project management Create, search, update, and complete Asana tasks, projects, sections, tags, workspaces, comments, and attachments over the Asana REST API - read-first defaults, idempotent mutations, and token-efficient TOON output.
brevo-axi brycehamrick Email marketing / Messaging Send and audit transactional email and SMS, manage campaigns, contacts, lists, attributes, CRM deals, companies, tasks, notes, senders, domains, and webhooks over the Brevo v3 REST API - sandbox-validated sends and --confirm-gated mutations with token-efficient TOON output.
firecrawl-axi brycehamrick Web data / Research Scrape, map, and crawl sites, search the web and research indexes, parse documents, run async research agents, and manage change monitors over the hosted Firecrawl MCP server - token-efficient TOON output.
n8n-axi brycehamrick Workflow automation Search, inspect, run, test, publish, and archive n8n workflows; triage executions; and manage projects, folders, tags, data tables, and credentials over n8n's instance-level MCP server - validate-then-create authoring with --confirm-gated mutations.
open-design-axi brycehamrick Design Browse and operate OpenDesign projects, files, artifacts, and generation runs from the shell, with offline reads from the local data directory when the daemon is down - --confirm-gated project create/delete and generation runs.
playwright-axi brycehamrick Browser automation Navigate, click, fill, and extract with combined operations, inline filtered snapshots, and TOON output. Wraps the playwright npm package's agent CLI.
tally-axi brycehamrick Forms / Surveys Read Tally forms and submissions field-by-field and manage FORM_RESPONSE webhooks over the public Tally REST API - pre-computed counts, truncation with a --full escape hatch, and token-efficient TOON output.
walter-axi brycehamrick AI content editing Detect AI-generated patterns, humanize drafts with locked keywords, and batch QA content through the WalterWrites MCP server - --confirm gates on credit-consuming writes.
wordpress-axi brycehamrick CMS / WordPress Publish and moderate posts, pages, media, terms, comments, users, and settings, and inspect plugins and themes over the core WordPress REST API - new content defaults to draft, publication and deletion are --confirm-gated.
mesheryctl-axi Meshery Authors Meshery / cloud native Agent-ergonomic wrapper around mesheryctl - token-efficient TOON list/view reporting, non-interactive execution, structured errors, and help[] next-step suggestions.

Built an AXI? Follow the contributor workflow to add it to this list.

Build Your Own AXI

Install the AXI skill to get the design guidelines and scaffolding for building an AXI-compliant CLI:

npx skills add kunchenguid/axi

This installs the AXI skill - a detailed guide with examples for each principle that your coding agent can reference while building. For your own AXI, expose an explicit setup command for session hooks as the primary integration, then ship an installable Agent Skill as a lower-overhead secondary path. Users only need one path, but hooks and skills complement each other when both are available.

Development

Browser Benchmark

The browser benchmark harness lives in bench-browser/. It compares browser automation tools across 16 browsing tasks.

pnpm install

# Run a single condition × task
pnpm --dir bench-browser run bench -- run --condition chrome-devtools-axi --task read_static_page

# Run the full matrix
pnpm --dir bench-browser run bench -- matrix --repeat 5

# Generate summary report
pnpm --dir bench-browser run bench -- report

# Render the social video
pnpm --dir bench-browser run render:social

The HyperFrames composition for the social asset lives in bench-browser/social/. Edit social/index.html for the animation and render docs/social/rendered/race.mp4 with pnpm --dir bench-browser run render:social.

Published results (490 runs): bench-browser/published-results/report.md

GitHub Benchmark

The GitHub benchmark harness lives in bench-github/. It runs agent tasks across different interface conditions and grades results with an LLM judge.

pnpm install

# Run a single condition × task
pnpm --dir bench-github run bench -- run --condition axi --task merged_pr_ci_audit --repeat 5 --agent claude

# Run the full matrix
pnpm --dir bench-github run bench -- matrix --repeat 5 --agent claude

# Generate summary report
pnpm --dir bench-github run bench -- report

Published results (425 runs): bench-github/published-results/STUDY.md

Contributing

Contributions targeting main must be submitted through the contributor workflow, which uses no-mistakes and guards release-please-generated files from hand edits.

Links

About

Design principles for agent ergonomics. Higher accuracy with lower token cost than both MCP and regular CLI.

Resources

Contributing

Stars

2.1k stars

Watchers

11 watching

Forks

Releases

Contributors

Languages