mastra-axi

mastra-axi is an AXI-compliant command-line interface for discovering and executing a Mastra application's agents, tools, and workflows. It exposes the same capability categories as @mastra/mcp, but through agent-native shell commands and compact TOON output instead of the MCP protocol.

MCP is useful for interoperable tool servers. For shell-capable coding agents, AXI avoids protocol schemas and repeated tool-call envelopes, reducing token overhead while adding fail-loud validation, structured stdout errors, and contextual next-step suggestions.

Install

npm install -g mastra-axi

Node.js 20 or newer is required.

@mastra/core is an explicit peer dependency (>=1.0.0 <2.0.0), so the CLI uses the same Mastra version as the target application instead of installing a second framework copy.

Project Discovery

Run mastra-axi from a Mastra project root. --dir <path> selects another root and defaults to the current working directory. The CLI resolves the module exporting your live Mastra instance in this order:

1. --entry <path> after the command
2. package.json#mastra-axi.entry
3. src/mastra/index.ts, src/mastra/index.js, src/mastra/index.mjs, mastra/index.ts, or mastra/index.js

TypeScript and ESM entries are loaded in-process. Export the instance as a named mastra export or as the default export:

import { Mastra } from "@mastra/core";

export const mastra = new Mastra({ agents, tools, workflows });

For a nonstandard entry, configure it once:

{
  "mastra-axi": {
    "entry": "src/application/mastra.ts"
  }
}

The included examples/sample application is offline and deterministic. From this repository, the root configuration points to that sample so node bin/mastra-axi.ts and node dist/bin/mastra-axi.js show live content immediately.

Commands

mastra-axi
mastra-axi agent list
mastra-axi agent view <name>
mastra-axi agent run <name> --prompt "..."
mastra-axi tool list
mastra-axi tool view <name>
mastra-axi tool call <name> --input '{"key":"value"}'
mastra-axi tool batch --input '[{"id":"first","tool":"...","input":{}}]'
mastra-axi workflow list
mastra-axi workflow describe <name>
mastra-axi workflow run <name> --input '{"key":"value"}'
mastra-axi workflow view <runId>

Place --dir <path> or --entry <path> after the command. Every command and subcommand accepts --help. Unknown flags fail with exit code 2 and a specific correction. Normal output and errors are TOON on stdout; stderr is reserved for diagnostics.

Home and tool list discovery include compact top-level input/output schemas with required fields and enum values, avoiding separate lookups for ordinary object-shaped tools.

Persistent Sessions And Batches

--serve loads the Mastra application once, then accepts ordered JSONL requests over stdio:

printf '%s\n' \
  '{"id":1,"argv":["tool","call","add","--input","{\"a\":2,\"b\":3}"]}' \
  '{"id":2,"argv":["agent","list"]}' \
  | mastra-axi --serve --dir ./my-app

Each response is { "id", "ok", "output" }, or a structured { "id", "ok": false, "error" }. The loaded project cannot be changed by individual requests.

Use tool batch to execute a sequential pipeline in one invocation. A $ref resolves a JSON Pointer against an earlier operation's raw output:

mastra-axi tool batch --input '[
  {"id":"sum","tool":"add","input":{"a":2,"b":3}},
  {"id":"scaled","tool":"multiply","input":{"a":{"$ref":"sum#/total"},"b":10}}
]'

Batches stop at the first failure and are not transactional.

Completed workflow status metadata is written with owner-only permissions to <project>/.mastra-axi/runs/ so workflow view <runId> remains useful when the project's own storage is not persistent. Workflow inputs and outputs are not copied into this fallback history. Add .mastra-axi/ to the application .gitignore.

Ambient Setup

Ambient context is opt-in. Ordinary commands never modify agent configuration.

mastra-axi setup hooks

This installs or repairs SessionStart integration for Claude Code, Codex, and OpenCode using the AXI SDK. Restart the agent session afterward. The live no-argument home view is injected for the current directory.

The installable Agent Skill is a secondary, on-demand discovery path:

npx skills add taltas/mastra-axi --skill mastra-axi

The committed skills/mastra-axi/SKILL.md is generated from the CLI's shared description and command list. pnpm check:skill detects drift.

Add To Your AGENTS.md

## Mastra

- Use `mastra-axi` to discover and execute this project's Mastra agents, tools, and workflows.
- Run `mastra-axi` first for live TOON context, then follow its `help:` suggestions.
- Use `mastra-axi <command> --help` for concise command-specific flags and examples.

Development

pnpm install
pnpm build:skill
pnpm lint
pnpm build
pnpm test
node bin/mastra-axi.ts
node dist/bin/mastra-axi.js

Benchmark

Does mastra-axi match @mastra/mcp correctness while using fewer agent tokens? The July 18, 2026 run compares both cold isolated tasks and a realistic long session against examples/sample. Both conditions achieved 100% correctness.

The long-session scenario uses one driver conversation and one persistent interface process for ten required conceptual operations: inventory discovery, an ambiguous pricing task, two multi-tool pipelines, a 40-record payload, a multi-step workflow, and an agent handoff. Discovery is paid once; AXI uses explicit tool batch pipelines while MCP performs equivalent sequential calls. The isolated family retains the six prior one-task-per-session cases as a cold-start comparison.

The run used OpenCode with openai/gpt-5.6-sol, five interleaved repeats, equal 304-character/52-token orientation seeds, the same Bash availability, and objective grading of both final values and required executed operations. AXI used one --serve process per complete scenario; MCP used one MCP server per complete scenario.

Avg Driver Total Tokens is the driver-inclusive headline: all input, cache reads/writes, visible output, and reasoning. Avg Interface Output Tokens separately tokenizes only the agent-visible TOON payload or MCP response; it is already reflected in later driver input and must not be added to the headline total. MCP tool-schema context is reflected only in the driver-inclusive total, not in the response column.

Realistic Long Session

Condition	Success %	Avg Interface Output Tokens	Avg Driver Total Tokens	Avg Turns
mastra-axi	100.0%	4,923	47,632	5.8
mastra-mcp	100.0%	3,294	61,421	9.0

AXI used 22% fewer driver tokens and 36% fewer turns in the amortized long-session regime.

Isolated Cold Tasks

Condition	Success %	Avg Interface Output Tokens	Avg Driver Total Tokens	Avg Turns
mastra-axi	100.0%	3,067	18,323	3.1
mastra-mcp	100.0%	830	14,409	2.7

See bench/ for the task and condition definitions, runner, raw-result format, grading, and reproduction instructions.

License

MIT