Aztrx AI

Catch the runtime crash your Error Boundary hid — and prove it with a test, not a log line.

Aztrx AI finds runtime bugs and business-logic holes — the crashes that ship to real users, including ones a React Error Boundary swallows (the errors window.onerror never sees), and the security gaps a scanner can't see: forged tokens the app believes, paywalls a direct link walks through, secrets the SSR spilled into HTML. Each finding comes back as an exact source line, a one-sentence business risk, and with --repro an executable Playwright repro that replays it. Then it fixes it.

npx aztrx-cli                    # find crashes — no key, no config, no URL to look up
npx aztrx-cli --fix              # fix them — free for common bugs

Run it in your project and it works out what your app is, starts your dev server if nothing is listening, scans, and stops the server again on the way out. Already have one running? It attaches and leaves it alone. Pass a URL (aztrx-cli run http://…) and it goes exactly there instead.

---

Why Aztrx AI

• Sees swallowed errors. Error Boundaries and window.onerror miss the errors your app catches. Aztrx reads the real throw-site stack off the Error object — a crash you've never seen in your logs becomes a finding you can't ignore.
• Explains the crash in one line. Every crash/error ships with a one-sentence diagnosis — why it happened and what to change (e.g. the value before .cartis undefined — guard with?.). Free, no key, right in the terminal and report.html`.
• Proves, not reports. With --repro (implied by --fix), every interaction crash ships with an executable .spec.ts repro and a flake-rate verdict — [deterministic 3/3], [flaky 3/5], or [unreliable]. A crash that can't be replayed reliably is reported as [unreliable] rather than dressed up as proof.
• Safe by default. A deny-by-default network guard blocks off-origin calls, a destructive-action deny-list refuses to click "delete", "pay", or "logout", and nothing leaves your machine unless you opt in.
• Knows your audience. --swarm scouts the app first — package.json, README, and the running UI — and synthesizes the people who actually use it. A shop gets rushed buyers and coupon hunters; a dashboard gets night-shift operators and filter wizards. Then it swarms the app with 1000 agents by default, weighted to that audience.
• Audits what you fear. --intent "проверь безопасность оплаты" — say what scares you in your own words, and the swarm picks the agents that answer it: key hunters scan every route's HTML for spilled secrets, identity forgers tamper with JWTs and check the app believes them, free riders walk straight onto premium routes. Proof or silence: a finding is reported only when the exploit worked end to end — and it's explained in business language ("a paid file can be downloaded for free"), not pentest jargon.
• Watches while you code. aztrx watch is security hot-reload: save a file, and a micro-swarm wakes — the saved code's own content becomes the intent, the delta-scan scopes to that file, and a new vulnerability gets healed and alerted in the terminal, ```diff attached, before you switch to the browser.
• Models the app as states. aztrx audit builds the state graph — Login → token → hidden Admin Panel — and the swarm attacks from the captured state, so authed-zone bugs reproduce (3/3) and patch. The kill chain prints per finding, and every verified patch ships a regression test that keeps the bug dead.

---

Quickstart

npm i -g aztrx-cli            # or use npx — no install needed

aztrx-cli                     # 1. find the crashes (no key, no account)
aztrx-cli --repro             # 2. prove them with an executable test
aztrx-cli --fix               # 3. fix them

Run it from your project root — it detects the framework, finds your dev server or boots it (npm run dev), and tears the server down when it exits. To point it at a server somewhere else, pass the URL: aztrx-cli run http://localhost:3000. It drives Chromium through Playwright (the first run downloads the browser automatically).

---

Fix it — free for common crashes

--fix has two engines:

1. Free, no key. For the most common crash — Cannot read properties of undefined/null — a built-in rule adds ?. (optional chaining) and applies the fix. No LLM, no key, no cost:

aztrx-cli run http://localhost:3000 --fix   # works out of the box for null/undefined derefs

2. Your model, for complex bugs. Logic errors, races, and anything the rule can't handle — point it at any model:

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# DeepSeek — its own key, its own API
export DEEPSEEK_API_KEY="sk-..."

# OpenAI (or whatever OPENAI_BASE_URL names)
export OPENAI_API_KEY="sk-..."

# …or any OpenAI-compatible provider: Grok, Gemini, Kimi, OpenRouter, Ollama
export AZTRX_API_BASE="https://openrouter.ai/api/v1"
export AZTRX_API_KEY="your-key"
export AZTRX_MODEL="anthropic/claude-sonnet-5"

Provider order: AZTRX_API_BASE → DEEPSEEK_API_KEY → OPENAI_API_KEY → Anthropic. Models default per provider (deepseek-chat, gpt-4o-mini, claude-sonnet-5); AZTRX_MODEL overrides. AZTRX_DEBUG_LLM=1 logs the raw model replies.

Every fix is redacted, sandboxed in a detached git worktree, compiler-checked, and gated on your test suite before you see it. --fix writes a patch and stops — nothing is committed to the branch you are on. --pr is the opt-in that goes further: it commits to a new aztrx/fix-… branch and opens a merge-ready PR from it. --regression-test drops the repro into your test dir so the bug can't come back.

---

More ways to run

Flag	What it does
--fuzz	coverage-guided chaos fuzz — steers toward code it hasn't reached
--http-fuzz	attack the server's endpoints (turns every 5xx into a repro)
--swarm	analyze the app, synthesize its audience, swarm it with 1000 agents
--intent <text>	what you fear, in your words ("проверь безопасность оплаты") — the swarm picks the agents
--roles <ids>	a subset of the standing catalog, e.g. novice,hostile,race-hunter
--diff [base]	infer the rules your latest change states from the live git diff (default base HEAD) and test them against the running app
--repo-rules	also infer stated rules from the code files under --repo
--agents N	total agent missions (tasks, not browsers)
watch [url]	security hot-reload — micro-swarm on every save, alert + auto-patch in the terminal
audit [url]	state-graph audit — kill chain per finding; with --fix, patches + regression tests
--login	auto-login to test authenticated pages
--badge / --pr-comment / --fail-on	CI artifacts
patrol <url>	autonomous loop — re-scan, fix, open a PR per bug
modernize <file>	rewrite legacy JS/TS into modern idiomatic syntax
studio	live dashboard on localhost:7331
hook install	scan every git push — block the ones that crash
mcp install	put aztrx inside your editor's agent (Claude Code, Cursor, VS Code)

Full list: aztrx-cli run --help, or the CLI reference.

---

Scan while you develop

Add a few lines and your dev server reports its own runtime crashes as you work — no second terminal, no separate command to remember. Same plugin either way; only the hook differs.

Vite

// vite.config.ts
import { aztrx } from "aztrx-cli/vite";

export default defineConfig({
  plugins: [aztrx()],
});

npm run dev
#   VITE v8.3.0  ready in 312 ms
#   ➜  Local:   http://localhost:5173/
#   [aztrx] 1 crash — first: src/Report.tsx:42
#   [aztrx] run `npx aztrx-cli` for the repro and the fix.

Next.js

Next has no config object to hang a plugin off, so it uses instrumentation.ts — the hook Next added for exactly this (Sentry and OpenTelemetry use it too):

// instrumentation.ts, next to app/ or src/
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { registerAztrx } = await import("aztrx-cli/next");
    registerAztrx();
  }
}

npm run dev
#   ▲ Next.js 16.3.2 (Turbopack)
#   - Local:        http://localhost:3001
#   [aztrx] 1 crash — first: app/page.tsx:18
#   [aztrx] run `npx aztrx-cli` for the repro and the fix.

The NEXT_RUNTIME guard is required, not decoration: Next compiles instrumentation.ts for the edge runtime as well, which has no child processes. The plugin itself does nothing outside next dev — a scan during next build or next start would point a browser at a real deployment. It finds the port Next actually bound, so it still works when 3000 was taken and Next moved to 3001.

Options and behaviour

// Vite: plugins: [aztrx({ … })]   Next.js: registerAztrx({ … }) — same options.
{
  maxActions: 50,      // shallower, faster walk
  fuzz: true,          // seeded chaos instead of the deterministic walk
  onResult: (r) => {}, // wire findings into your own tooling
}

Both plugins are a sentinel, not a reporter: silent until the scan finishes, then one line. Run aztrx-cli for the full report, the executable repro, and the fix. Findings also land in .aztrx/ as usual.

The scan runs as a separate process, killed when the dev server stops. That is deliberate: a scanner that crashes, hangs, or leaves a browser behind must never be able to take your dev server down with it — and it dies with the parent even if the parent is hard-killed. Set AZTRX_DEV_SCAN=0 to skip a scan without editing the config.

---

Scan before you push (git hook)

One command and every git push scans your app first:

aztrx-cli hook install
#   ✓ pre-push hook installed.
#     .git/hooks/pre-push
#     Every `git push` now scans the app and blocks on a crash.
#     Skip one push with `git push --no-verify`, or a run with AZTRX_HOOK_SKIP=1.

A push that found something:

[aztrx] 1 changed file: src/Cart.tsx. Scanning the app…
[aztrx] 1 crash · 1 warning — first: src/Cart.tsx:42
[aztrx] run `npx aztrx-cli` for the repro and the fix.
[aztrx] push blocked — 1 crash/error finding in your app.
[aztrx] fix them and push again; to push anyway, `git push --no-verify`.

It scans your app, not your diff — a changed file is the trigger, not the scope. A crash at Cart.tsx:42 usually comes through a useCart() that changed three files away, and a diff-shaped scan would look straight past it.

It stays out of the way

Push a README and it says so and gets out of the way in about a second:

[aztrx] skipped — only docs, metadata or assets changed (1 file).

The skip list is deliberately short and boring: .github/, .vscode/, .aztrx/, LICENSE, .gitignore, .md, images. Anything arguable — lockfiles, config, .mdx — is not on it, because a wrong skip is a missed crash, which is the one thing this hook exists to prevent. When it cannot tell what changed (a branch the remote has never seen, a shallow clone) it scans the whole app and says why.

git push --no-verify	skip this push
AZTRX_HOOK_SKIP=1 git push	same, for scripts
aztrx-cli hook uninstall	remove it

It cannot block you by accident

Aztrx blocks a push because it found a crash — never because it is broken:

• Not installed, not on PATH → the push proceeds.
• The scan fails, or never finishes → the push proceeds, with the reason printed. AZTRX_HOOK_TIMEOUT (ms, default 300000) caps a single scan.
• A failed scan is never reported as clean. "I could not look" is a different sentence from "nothing there", and it stays that way.

A hook that blocks pushes when it is merely broken gets turned off, and then it catches nothing.

The installed file is a short POSIX shim that calls back into the CLI, so npm i -g aztrx-cli@latest upgrades the hook as well — nothing to reinstall. hook install is idempotent, installs where git actually looks (so core.hooksPath — husky, Lefthook — is respected), and refuses to overwrite a pre-push hook it did not write unless you pass --force.

Not handled: under Yarn PnP there is no node_modules/aztrx-cli to find, so the hook skips silently. Safe, but useless — use npm, pnpm, or Yarn with nodeLinker: node-modules.

---

Use aztrx from your editor (MCP)

Your editor's agent can write code but cannot run it. It can compile, lint, and typecheck — none of which open a page and click the button. So it will tell you a change works when all it knows is that the change parsed.

aztrx mcp gives the agent the missing step: it drives the app in a real browser and hands back the runtime crashes it produced, with an executable repro attached.

npx aztrx-cli mcp install
#   ✓ Claude Code — .mcp.json — added.
#   ✓ Cursor — .cursor/mcp.json — added.
#   • VS Code — no .vscode/ in this project
#
#   Restart your editor — or reload its window — to pick the server up.

It writes the config for the editors your project actually uses, and only ever adds one key to a file it reads first. Your other MCP servers are left alone. If a config will not parse it refuses rather than overwriting — a missing comma should never cost you your setup — and --force is the escape hatch, which saves a .bak first. mcp uninstall removes only our entry and keeps the file.

The four tools

Tool	What it does	Costs
aztrx_audit	The security co-founder: say what you fear ("проверь безопасность оплаты"), and the swarm exploits it — proven findings in business language, with a curl/steps proof and a patch or the one command that produces it.	tens of seconds to minutes
aztrx_scan	Drives the app, reports crashes/errors with source locations. Boots the dev server itself if none is running.	tens of seconds
aztrx_repro	The minimized steps and the compiled Playwright spec for one finding. Reads the scan that already ran.	free
aztrx_fix	Patch → verify in a git worktree by replaying the repro → optionally write it into your tree.	one model call

The scan returns a compact projection with a scanId; the detail — the action sequence, the spec, the diff — is fetched by handle. A stack trace in the agent's context on every scan is how a useful tool becomes an expensive one.

aztrx_fix needs a key (ANTHROPIC_API_KEY, or AZTRX_API_BASE + AZTRX_API_KEY + AZTRX_MODEL for any other provider). Without one it returns no-llm and attempts nothing. Scanning and proving never need a key. Aztrx never commits: apply: true writes working-tree files, and git diff is the review.

What it will not do

• No --allow-destructive, --fuzz, or --http-fuzz over MCP. The tool drives a real browser against an app you are working in. An agent should not be able to reach for data-mutating controls because a prompt suggested it. If you want the fuzzer, that is a deliberate aztrx-cli run in a terminal.
• A scan that could not run is an error, never "no findings." If the app would not boot or the browser could not reach it, the tool returns isError with the reason — it does not return an empty list. An agent that reads 0 crashes from a scan that never happened will tell you the code is fine.

Protocol support

MCP changed shape in its 2026-07-28 revision: the initialize handshake is gone, replaced by per-request metadata. Editors are split across that line — Claude Code speaks the new revision, and Cursor still speaks 2025-11-25.

aztrx mcp speaks both and picks per request, which is why it works in both editors today and will keep working as the others move. It is ~550 lines — the protocol layer and the server — with zero new dependencies; neither official SDK covers both revisions, and the legacy one pulls seventeen runtime dependencies (express, cors, jose, ajv…) for a stdio server that needs none of them.

---

Autonomous patrol

aztrx patrol is the looped version of run --fix: point it at a running app and it re-scans on an interval, fixes anything new, and opens a PR per bug — no human in the middle. Each PR body carries a recorded repro: a short animated GIF that replays the crash step-by-step, so a reviewer sees the bug happen before the fix.

aztrx-cli patrol http://localhost:3000        # re-scan every 10 min, open a PR per new bug
aztrx-cli patrol http://localhost:3000 --once # one scan, then exit (great for CI/cron)
aztrx-cli patrol http://localhost:3000 --batch # group a cycle's fixes into one PR

Flag	What it does	Default
--interval <s>	Seconds between scans	600
--max-fixes <n>	Max PRs to open per session	5
--max-spend <n>	Hard cap on paid LLM generations per session	unlimited
--retry-after <s>	Cooldown before an unfixable bug is retried	1800
--batch	Group all of a cycle's fixes into one PR	one PR per bug
--once	Run a single scan then exit	loop forever
--fuzz / --workers <n>	Detection mode / parallelism (pass-through to run)	—
--login	Auto-login before each pass — needs $AZTRX_AUTH_EMAIL + $AZTRX_AUTH_PASSWORD, or --login-email / --login-password	off
--storage-state <path>	Playwright storage-state JSON for authenticated pages	—

Guardrails keep the loop from running away: it only stages the files a patch touched (never git add -A), dedups by crash fingerprint (a re-scan won't re-open the same PR), backs off from unfixable bugs, and respects a session-wide LLM spend cap.

---

Security

• Local-first. Nothing leaves your machine unless you opt in.
• Never touches the branch you are on. --fix and --heal land a patch in a detached worktree for your review — git diff is the review. The two things that do commit are the two whose entire job is to open a PR: --pr, and patrol. Both commit to their own aztrx/fix-… branch, stage only the files a patch touched, and return you to the branch you started on.
• Redacted. Secrets are stripped from the file, error, and stack before any LLM call.
• Deny-by-default network. Off-origin calls are blocked; destructive clicks (delete/pay/logout) are refused.
• .aztrx/ is gitignored — repros, reports, and patches stay out of history.

---

Continuous Integration (GitHub Action)

Runtime gate on every PR — runs aztrx-cli run --fail-on --repro --heal, posts a comment with the repro + patch, and fails on a crash/error.

# .github/workflows/ci.yml — composite action, inline
on: pull_request
jobs:
  aztrx:
    runs-on: ubuntu-latest
    timeout-minutes: 30                        # recommended — see below
    permissions: { contents: read, pull-requests: write }
    steps:
      - uses: actions/checkout@v4
      - uses: Aztrx-AI/[email protected]
        with:
          token: ${{ github.token }}
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}   # optional — enables --heal

That is the whole setup: aztrx detects the framework, boots your dev server, scans, and shuts it down again. Already have a server running, or want to control how it starts? Pass a URL and the action stays out of the way:

        with:
          url: http://localhost:3000
          start-command: npm run dev           # boot the app in the background first
          wait-for: http://localhost:3000      # defaults to `url`
          token: ${{ github.token }}

A status badge (--badge) and PR comment (--pr-comment) work the same way — regenerate in CI on every push.

What the check tells you

uses: Aztrx-AI/[email protected] runs aztrx-cli 0.5.2 — the action reads its own version, so the tag selects the engine, not just the wrapper.

A red check has two different meanings, and the message says which:

aztrx detected crash/error findings	it scanned, and found something. Fix it, or run npx aztrx-cli locally for the repro.
aztrx did not run (exit code: N)	the scan never produced a result — a bad version pin, a registry failure, a broken config. Not a verdict about your app. The last lines of the run are printed to explain it.

Set timeout-minutes on the job. The default args include --repro and --heal, which drive your app repeatedly and can call a model — without a ceiling, one hung browser spends GitHub's 6-hour job default finding nothing.

On a fork pull request the token is read-only, so the comment is skipped with a warning and the check still reports the scan result. --heal needs ANTHROPIC_API_KEY, which forks do not receive; it skips cleanly rather than failing.

Prefer not to wire it inline? The same thing is packaged as a reusable workflow:

jobs:
  aztrx:
    uses: Aztrx-AI/aztrx/.github/workflows/[email protected]
    secrets:
      anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

---

CLI reference

aztrx-cli run --help is grouped by intent (Detect / Prove / Fix / Report & ship / Auth); the table below is the complete reference — including flags hidden from --help (aliases and niche tuning knobs). aztrx-cli --version (or -V) prints the installed version, read from the package's own package.json so it cannot drift from what npm shipped.

The commands that are not run:

Command	What it does
mcp	Serve the MCP server on stdio (this is what an editor's config runs)
mcp install [--force]	Add aztrx to .mcp.json / .cursor/mcp.json / .vscode/mcp.json, merging one key
mcp uninstall	Remove only that key
init	Scaffold aztrx.config.ts
hook install | uninstall | run	The pre-push hook
watch [url]	Security hot-reload: watch the project, micro-swarm every save, alert + auto-patch in real time
audit [url]	State-graph audit: the Mapper builds the app's state graph, the swarm attacks from the richest authed state, kill chain per finding — with --fix it patches and generates a regression test
patrol [url]	Autonomous scan → fix → PR loop
modernize <file>	Rewrite a legacy file with an LLM
studio [--port n]	Live dashboard (7331)

Flag	Description	Default
--no-boot	Attach to a running dev server only — never start one yourself	boots when needed
--fuzz	Seeded chaos fuzzing instead of the deterministic walk	—
--http-fuzz	Server-side mutation fuzzing — hostile requests against the target origin	—
--http-fuzz-mutations	With --http-fuzz: also send POST/PUT body mutations (default: GET-only)	—
--allow-destructive	Opt-in: test destructive controls/endpoints (delete/pay/logout/checkout) — can mutate real data	—
--repro	Minimize (ddmin) → emit Playwright spec → validate flake rate	—
--heal	Generate + verify a fix (implies --repro)	—
--fix	Find → explain → heal → apply — the one-command fix (free for null/undefined derefs)	—
--magic-fix	Hidden alias for --fix (deprecated)	—
--explain	Print a human-language summary of the findings	—
--yes / -y	Auto-apply verified fixes without prompting (with --fix)	—
--pr	Open a merge-ready PR with the verified fixes (with --fix)	—
--lang <code>	Language for the human-language summary (en, ru)	en
--upload	Stream run findings to the cloud ingest backend	—
--api-key <key>	Auth key for --upload / --share-data — distinct from the model provider key	$AZTRX_CLOUD_API_KEY
--cloud-url <url>	Ingest server base URL	https://api.aztrx.app

The hosted ingest is not live yet. --upload and --share-data point at https://api.aztrx.app, which does not currently resolve, and the server in server/ has no deployment. The routes are real and tested — tests/server-ingest.test.ts drives the actual createIngestServer over HTTP, including the fingerprint dedup — but there is no host behind the default URL. Until there is, point --cloud-url at your own instance of server/. A failed upload now says so on stderr instead of being discarded, and --api-key takes $AZTRX_CLOUD_API_KEY: it is deliberately not $AZTRX_API_KEY, which is your model provider key and has no business on the wire as an ingest credential.

---

Output artifacts

Every run writes self-contained artifacts inside .aztrx/ (gitignored):

.aztrx/
├── report.html                  # interactive triage report
├── repro/<id>.spec.ts           # minimal, executable Playwright repro
├── heal/<id>.patch              # gated, compiler-checked fix (one per finding)
├── events.jsonl                 # run log (streamed by `aztrx-cli studio`)
├── patrol.json                  # patrol cross-run memory (handled fingerprints)
├── pr-comment.md                # GitHub PR markdown (with --pr-comment)
└── badge.svg                    # status badge (with --badge)

And one artifact that is not gitignored — it belongs in your repo:

__aztrx_tests__/                 # Prove-It-Fixed: CI-ready Playwright regression
    prevent-actions-crash.spec.ts    tests — one per verified patch, with a name
    prevent-paywall-bypass.spec.ts   that says what it guards

Every healed patch generates one: the repro spec rewritten with inverted assertions (the attack must now be blocked), seeded with the auth state it needs, ready for npx playwright test. It passes on the patched code and fails on the unpatched code — that's the point.

aztrx patrol also writes a aztrx-media/<fingerprint>.gif recorded repro next to the project root — the animated proof inlined in each patrol PR body.

---

Benchmarks

Aztrx is scored against two corpora — a framework-agnostic archetype baseline and a corpus of real Next.js 16 App Router apps (Turbopack, client components), each with one seeded runtime bug:

corpus	detection	deterministic repro
13 Next.js 16 apps	13/13 · 100% recall	12/12 · 100%
13 vanilla archetypes	13/13 · 100% recall	11/12 · 91.7%

One archetype is 13-swallowed-boundary — a crash caught by an Error Boundary and logged via console.error, never rethrown. A pageerror-only detector scores 0/1 on it. It is the README's headline claim, so it lives in the corpus where a regression would fail the benchmark.

Reproduce it yourself: npm run bench (archetypes) and cd bench/frameworks && npm run bench (Next.js corpus). Per-case results and scope notes live in bench/frameworks/RESULTS.md and bench/RESULTS.md.

Contributing

git clone https://github.com/Aztrx-AI/aztrx
cd aztrx
npm install
npx playwright install chromium
npm run build

# smoke fixture (throws on the "Break me" button)
node fixtures/serve.mjs &
node dist/cli.js http://localhost:8901/crash.html --repo fixtures --repro
# → one ● crash mapped to crash.html:13:15, minimized to 1 step

Support

If Aztrx AI saved you hours of debugging, you can support the author directly — name a fair price on Polar.sh:

Donate on Polar.sh →

License

Apache-2.0 © DanisChaparov