sentry-axi wraps the Sentry API with an AXI-compliant CLI, plus a delegation layer to the official sentry-cli for everything that needs Sentry's chunked-upload protocol.

• Token-efficient: TOON-encoded output and pre-rendered stack traces, instead of the 50-200KB of JSON a raw Sentry event actually is
• Combined operations: one command lists, mints refs, and suggests the next step; seer starts a run and polls it to completion
• Contextual suggestions: every response ends with the actual next commands, refs already filled in
• Built for the triage loop: issues -> stacktrace -> seer/suspect -> resolve
• Everything the official CLI does: releases, deploys, sourcemaps, debug files, cron monitors
• Multi-project native: named sessions hold independent org/project scopes at once

Quick Start

Install the skill in the Agent Skills format with npx skills:

npx skills add ammar00sheikh/sentry-axi --skill sentry-axi -g

The skill (generated from the CLI's own guidance) teaches your agent when and how to use sentry-axi; it loads on demand when the agent recognizes a production-error task.

Then authenticate and pin a scope:

sentry-axi login --token <token>       # or just set SENTRY_AUTH_TOKEN
sentry-axi use acme/frontend
sentry-axi issues

If the repo is already set up for the official sentry-cli (a .sentryclirc or sentry.properties with an org/project), sentry-axi picks that up automatically and you can skip both steps.

Create a token at https://sentry.io/settings/account/api/auth-tokens/ with scopes org:read, project:read, project:write, event:read.

Requirements: Node >= 20. The official sentry-cli binary is optional — only sourcemap and debug-file uploads need it, and sentry-axi tells you if it is missing.

What the Agent Sees

$ sentry-axi issues
issues:
  project: acme/frontend
  query: is:unresolved
  period: 24h
  sort: freq
  found: 3
  generation: g1
results[3]{uid,shortId,level,events,users,age,title,culprit}:
  g1:1,FRONTEND-4F,error,1.2k,89,3h,"TypeError: Cannot read properties of undefined (reading 'name')",app/components/UserCard
  g1:2,FRONTEND-2A,error,310,204,1d,"TimeoutError: payment gateway did not respond",src/payments/gateway.py
  g1:3,FRONTEND-9C,warning,88,12,6h,"Network request failed",app/lib/fetch
help[4]:
  Run `sentry-axi stacktrace @g1:1` to see where FRONTEND-4F throws
  Run `sentry-axi issue @g1:1` for full detail (tags, counts, first/last seen)
  Run `sentry-axi seer @g1:1` for AI root-cause analysis
  Narrow with Sentry search syntax: `sentry-axi issues --query "is:unresolved is:unassigned level:error"`

$ sentry-axi stacktrace @g1:1
issue:
  uid: "g2:1"
  shortId: FRONTEND-4F
  event: a1b2c3d4e5f6...
  release: 4.2.0
  when: 3h
stacktrace:
TypeError: Cannot read properties of undefined (reading 'name')  [unhandled]
  > UserCard at app/components/UserCard.tsx:42
    Profile at app/pages/Profile.tsx:18
  ... 2 library frames
help[4]:
  Run `sentry-axi seer @g2:1` to have Sentry's AI diagnose the root cause
  Run `sentry-axi suspect @g2:1` to find the commit that introduced it
  ...

Note the > on the first frame. Sentry stores frames oldest-caller-first, so the frame that actually threw is last in the payload — sentry-axi reverses them, because an agent reads the first line as the culprit. Library frames collapse to one line so the app code stays readable; --full shows them all, --context adds source lines around the throw.

Refs carry a g<N>: generation prefix. Unlike its sibling flutter-axi, refs here stay valid across re-listings (a Sentry issue id is immutable, so @g1:3 cannot come to mean a different issue), and issues can always be addressed without a listing at all:

sentry-axi stacktrace short:FRONTEND-4F         # straight from an alert email
sentry-axi issue https://acme.sentry.io/issues/4509172/

The Triage Loop

sentry-axi issues                      # what is broken (mints refs)
sentry-axi stacktrace @g1:1 --context  # where it throws, with source lines
sentry-axi breadcrumbs @g1:1           # what the user did just before
sentry-axi tags @g1:1                  # is it one release? one browser? one customer?
sentry-axi seer @g1:1                  # Sentry's AI root-cause analysis
sentry-axi suspect @g1:1               # which commit touched those frames, and who wrote it
sentry-axi resolve @g1:1               # ...once you have shipped the fix

--sort freq (most events) and --sort user (most users affected) routinely name different issues. Pick the one the question actually asks.

Releases, Deploys, and Sourcemaps

sentry-axi releases
sentry-axi release 4.2.0                                  # commits + deploys + new issues
sentry-axi issues --query "first-release:4.2.0"           # exactly what this release introduced

sentry-axi release new 4.2.1 --ref $(git rev-parse HEAD)
sentry-axi sourcemaps inject ./dist
sentry-axi sourcemaps upload ./dist --release 4.2.1
sentry-axi deploy 4.2.1 --env production

Sourcemap and debug-file commands delegate to the official sentry-cli, which implements Sentry's chunked-upload protocol. upload defaults to --strict, so uploading zero files is a loud error rather than a silent success — a silently-empty upload is the most common reason unminified stack traces never show up.

Performance

sentry-axi perf                          # slowest transactions by p95 + accepted/dropped volume
sentry-axi perf --period 7d --limit 20

Pre-aggregated: a ranked table, not a span dump.

Multi-Project

One session = one org/project scope. Add --session <name> to any command:

sentry-axi --session web use acme/frontend
sentry-axi --session api use acme/backend
sentry-axi --session api issues

Each session keeps its own scope and its own refs, so they never collide.

How It Works

sentry-axi CLI  (axi-sdk-js: TOON output, structured errors, suggestions)
  ├─► Sentry HTTP API  ─►  issues, events, stack traces, Seer, releases, perf
  └─► official sentry-cli  ─►  sourcemap / debug-file uploads (chunked upload protocol)

Every invocation is a short-lived process: resolve config, make one or two requests, render, exit.

There is no bridge process. Its siblings (flutter-axi, chrome-devtools-axi) run a detached daemon holding a persistent MCP session, because a running app or browser is long-lived and stateful. Sentry is a stateless HTTPS API — there is nothing to keep alive, so all of that complexity is simply absent.

Does it use MCP?

No — and that is the point.

Sentry ships an official remote MCP server. sentry-axi is an alternative to it, not a wrapper around it: agents use it through plain shell commands, with no MCP configuration at all. That is the AXI thesis — that a CLI with pre-rendered, token-efficient output beats the same capability delivered as MCP tools, because the agent stops paying for tool schemas and raw JSON payloads it has to reduce itself.

The bench/ harness exists to test that claim rather than assert it, by running the same triage tasks through both interfaces and comparing tokens, cost, turns, and success rate.

Benchmarks

Agent ergonomics is measurable, and the whole point of an AXI is token efficiency: the same backend data should cost an agent far fewer tokens as sentry-axi's rendered output than as the raw payload it is derived from.

Token efficiency (measured)

Measured against a live Sentry instance — a real .NET project with 24 unresolved issues and an 11-frame stack trace. For each operation we tokenized both what sentry-axi prints (the text the agent reads) and the raw Sentry Web API JSON for the same data (what a raw-JSON MCP tool, or direct API access, would feed the agent):

| Operation | Raw API tokens | sentry-axi tokens | Reduction | | -------------------------------- | -------------: | ----------------: | --------: | | List issues (24 issues) | 12,239 | 1,608 | 87% | | Issue detail + top tags | 1,747 | 350 | 80% | | Stack trace (1 event, 11 frames) | 12,775 | 641 | 95% | | Total | 26,761 | 2,599 | 90% |

The raw payloads cost 10.3× the tokens of sentry-axi's output for the same information. The stack trace is the extreme case: a single Sentry event is ~42KB of JSON — every frame carries vars, source context, module paths, and redundant id fields — which sentry-axi collapses to the app-code frames an engineer can act on. The listing case is TOON's tabular encoding stating field names once instead of per-row.

These numbers are real and reproducible — the exact capture-and-tokenize steps and the raw/rendered artifacts are in bench/published-results/token-efficiency.md.

Full agent-task study (pending)

Token efficiency is the core of the claim but not the whole story. The end-to-end study — turns, cost, wall-clock, and task success rate for an agent driving sentry-axi versus Sentry's official remote MCP server, scored by an LLM judge — is implemented in bench/ (replicating the axi methodology) but has not been run yet. It executes mutating tasks (resolve, assign), so it refuses to run against anything but a dedicated throwaway project, and snapshots/restores issue state between repeats. When it runs, its numbers land in bench/published-results/ beside the token measurement above — this README will not carry fabricated agent-task numbers before then.

Other Ways to Install

Curl installer

curl -fsSL https://raw.githubusercontent.com/ammar00sheikh/sentry-axi/main/install.sh | bash

Clones into ~/.sentry-axi/cli (override with SENTRY_AXI_HOME), builds, and links sentry-axi onto PATH. Re-running updates the install.

From source

git clone https://github.com/ammar00sheikh/sentry-axi.git
cd sentry-axi
npm install
npm run build
npm link        # puts `sentry-axi` on PATH

Session hook

Want the current Sentry scope and open-issue count fed into every agent session, instead of loading on demand?

sentry-axi setup hooks

Installs a SessionStart hook for Claude Code, Codex, and OpenCode. Restart your agent session afterwards. Development entrypoints (npm run dev) are guarded from accidental hook installation.

Self-Hosted Sentry

Pass your instance URL at login. It is stored with the token, because a token is only valid against the instance that issued it — so you set it once and never think about it again:

sentry-axi login --token <token> --url https://sentry.internal.acme.com
sentry-axi use acme/backend
sentry-axi issues

No environment variables needed. (SENTRY_AXI_URL still works and overrides the stored value, which is what CI should use.)

Create the token at <your-instance>/settings/account/api/auth-tokens/, not sentry.io.

sentry-axi doctor reports the resolved URL, token, and scope — and where each value came from. It is the first thing to run when anything looks wrong.

Development

npm install
npm test          # unit suite (no network needed)
npm run test:e2e  # live suite, needs SENTRY_AUTH_TOKEN + a real org/project
npm run build     # compile to dist/

Architecture notes for coding agents: AGENTS.md. Contribution conventions: CONTRIBUTING.md.

Limitations

• suspect (suspect commits) needs the repository linked to Sentry and commits associated with releases; without that Sentry has nothing to correlate and the command says so.
• seer needs Seer enabled for the org; if it is not, the command fails with SEER_UNAVAILABLE rather than a raw 4xx.
• perf needs performance monitoring enabled on the project; a project with no transaction data reports that explicitly instead of an empty table.
• Sourcemap and debug-file uploads require the official sentry-cli binary (npm i -g @sentry/cli). Everything else works without it.