magi-linear-axi

Agent-native Rust CLI for direct, non-interactive Linear GraphQL operations. Modeled commands cover issues, teams, users, projects, cycles, milestones, initiatives, labels, documents, comments, relations, and updates; raw GraphQL remains available when needed.

Why magi-linear-axi?

Published v0.2.1 benchmark: In a bounded compact read-only cohort, AXI used 38.9% fewer provider-reported tokens and 17.0% lower provider-reported cost than official Linear read-only MCP, while agent wall time was 14.2% higher. This is aggregate, directional evidence—not a universal or causal claim.

magi-linear-axi is built for reliable agent workflows: explicit and auditable commands, compact TOON output, stable exit codes, bounded reads, broad modeled Linear operations, raw GraphQL, and schema export. Published read-only benchmark results favor it for token and cost efficiency, making it a strong default for agents working with Linear.

Quick start

Agents: Use the cross-platform setup prompt to install magi-linear-axi, configure supported agent integrations and Agent Skill destinations, and verify authentication without exposing the Linear API key.

Requires Rust 1.87+, a Linear personal API key, and network access. Install Rust with official rustup if needed.

Install from crates.io and configure authentication:

cargo install magi-linear-axi --locked
export LINEAR_API_KEY='lin_api_your_key'
magi-linear-axi auth whoami
magi-linear-axi team list

On Windows, set LINEAR_API_KEY using PowerShell or Command Prompt syntax instead of export.

--format json means compact JSON for API-backed results and post-parse application errors; parser-level failures and documented plain-text commands remain outside strict JSON. Default output is compact TOON. Strings truncate after 240 Unicode code points; --full disables truncation.

magi-linear-axi setup installs Claude Code, Codex, OpenCode, and Pi context integrations by default. Use --claude, --codex, --opencode, or --pi to select targets.

Common reads

magi-linear-axi issue mine --fields compact
magi-linear-axi issue query --team ENG --search authentication --fields compact
magi-linear-axi issue view ENG-123 --fields compact
magi-linear-axi project view PROJECT_ID --fields compact
magi-linear-axi api '{ viewer { id name email } }'

Use --format json for downstream JSON consumers. Run magi-linear-axi --help or focused command help before unfamiliar operations.

Output and safety essentials

• No prompts. Inputs come from args, flags, files, stdin, or environment.
• Success data and application errors go stdout; diagnostics go stderr.
• Exit 0 means success/empty/safe no-op; 1 operational failure; 2 usage failure.
• Read-only modeled requests retry transient failures and HTTP 500/502/503/504 up to three total attempts. Mutations, uploads, raw API, raw pagination, and GraphQL errors never retry.
• API key must be non-empty LINEAR_API_KEY; never stored, printed, or placed in hooks.
• Raw GraphQL can mutate anything key permits. Review query, variables, returned success, and postconditions. Never blindly retry ambiguous mutations.
• Modeled issue mutations accept fields they do not send. Check current mutation limits; verify every intended postcondition.
• Remote endpoints require HTTPS; HTTP is accepted only for loopback hosts.

Benchmark evidence

Published v0.2.1 compact read-only benchmark results:

• 24/24 deterministic checks passed.
• 24/24 judge evaluations passed.
• Zero observed safety, policy, or unexpected incidents.
• 38.9% fewer provider-reported tokens and 17.0% lower provider-reported cost in comparison cohort.

Agent wall time was 14.2% higher, so evidence most strongly favors magi-linear-axi when token and cost efficiency matter. The scope was 8 tasks × 3 repeats per interface (48 compact cells). Results are aggregate-only and directional; raw cohort artifacts are not published. See results, method, and caveats, harness methodology, and showcase.

Documentation

• CLI reference: contract, configuration, commands, raw GraphQL, setup, completions.
• Agent setup prompt: guided installation, secure API-key configuration, authentication, context integrations, and Agent Skill setup.
• Safety: retries, mutation verification, limits, security boundaries.
• Development: repository workflow, tests, and release gates.
• Agent Skill
• Changelog · release checklist · license

Development

Build and contributor workflow:

git clone https://github.com/magimetal/magi-linear-axi.git
cd magi-linear-axi
cargo install --path . --locked
cargo +1.87.0 fmt --check
cargo +1.87.0 test --locked
cargo +1.87.0 clippy --all-targets --all-features --locked -- -D warnings
cargo +1.87.0 build --release --locked

Integration tests use local GraphQL mocks and do not require Linear access. See development details and release checklist.