bugsnag

---

name: bugsnag description: Use when user wants to inspect Bugsnag errors for Gramax (top events, frequent crashes, impact ranking, error detail, mark fixed). Triggers on "bugsnag", "багснаг", "top errors", "most frequent crashes", "что в багснеге", "посмотри багснаг", "fix bug in bugsnag", "resolve error", "mark fixed", "examine error", "show error". Two Bugsnag projects exist: Gramax-PROD and Gramax-DEV. Pass full project name via --project <name>. Splits results by platform (TAURI/NEXT/BROWSER/...) parsed from message prefix. Includes stacktrace + full event metadata. Outputs JSON. Before patching code, invoke the superpowers:systematic-debugging skill — feed it the show --error <id> output. Marking an error fixed in Bugsnag is not the actual fix — the code change must reach the latest release branch via either (1) a GitLab MR targeting the latest release/* branch, or (2) a commit on develop followed by a cherry-pick to the latest release/* branch. Use fix only after the change is merged/cherry-picked.

bugsnag — query + manage Gramax Bugsnag errors

CLI to inspect Bugsnag errors with impact ranking and stacktraces, examine a single error in full detail, mark errors fixed, and post comments.

Two Bugsnag projects on the SaaS org:

• Gramax-PROD — production crashes
• Gramax-DEV — pre-release / nightly

Pass the full project name as --project <name> (case-insensitive). --project all (default for stats) scans every project whose name starts with Gramax.

Setup

1. Get a Personal Auth Token (PAT) from Bugsnag SaaS:
   • app.bugsnag.com → avatar → My Account Settings → Personal auth tokens → Generate
   • Token shown only once. Copy immediately.
2. Export:

   export BUGSNAG_API_PAT_KEY=<token>
   # optional: pin org if user has access to multiple
   export BUGSNAG_ORG=<org-slug-or-name>
   

Token is read-only at the account level by default; write ops (fix/comment) require token to have project write access.

Platform detection

Gramax BugsnagLogger prepends [<ENV>] to error messages (see core/extensions/loggers/BugsnagLogger.ts:26-33). CLI parses the tag from errorClass or message:

• TAURI, NEXT, BROWSER, DOCPORTAL, STATIC, CLI
• absent prefix → unknown

Impact formula

impact = countDisplayed / 10 + countUndisplayed / 100

countDisplayed — events where metaData.user.errorDisplayed=true (user saw an error modal). Estimated by sampling up to 100 most-recent events per error and applying the ratio to the total count. countUndisplayed — silent errors.

With --no-split, no sampling is done and impact collapses to count / 100.

Commands

stats — list top errors (read-only)

bun .claude/skills/bugsnag/scripts/bugsnag.ts stats [flags]

Flag	Default	Meaning
--since <window>	30d	24h, 7d, 30d, or ISO date 2026-05-01T00:00:00Z
--top <N>	20	Top N errors per project (max ~30 by Bugsnag API)
--project <name>	all	Full project name (Gramax-PROD, Gramax-DEV), or all (every Gramax-* project)
--platform <p>	all	tauri, next, browser, docportal, static, cli, or all
--no-stack	off	Skip stacktrace fetch
--no-split	off	Skip displayed/undisplayed sampling (impact = count/100)
--pretty	off	Pretty-print JSON

Output (stdout): JSON. Events sorted by impact desc.

{
  "window": {"since": "2026-05-26T00:00:00Z", "until": "2026-06-02T00:00:00Z"},
  "totals": {
    "by_project": {"Gramax-PROD": 1234, "Gramax-DEV": 56},
    "by_platform": {"tauri": 800, "next": 230, "browser": 200, "unknown": 60}
  },
  "events": [
    {
      "project": "Gramax-PROD",
      "platform": "tauri",
      "errorId": "5f...",
      "errorClass": "TypeError",
      "message": "[TAURI] Cannot read 'x' of undefined",
      "count": 412,
      "countDisplayed": 12,
      "countUndisplayed": 400,
      "impact": 5.2,
      "firstSeen": "...",
      "lastSeen": "...",
      "topFrame": "core/extensions/bugsnag/logic/sendBug.ts:42 sendBug",
      "stacktrace": [{"file": "...", "line": 42, "method": "sendBug", "inProject": true}],
      "latestEvent": {
        "id": "...",
        "received": "...",
        "context": "...",
        "device": {"osName": "macOS"},
        "app": {"version": "2026.6.0", "releaseStage": "production"}
      },
      "url": "https://app.bugsnag.com/<org>/<project>/errors/5f..."
    }
  ]
}

show — examine one error by ID (read-only)

bun .claude/skills/bugsnag/scripts/bugsnag.ts show --error <id> --project <name> [--pretty]

Returns the full latest event for the error: full stacktrace, all metaData tabs (custom + logic_props + user + ...), device, app, request, last 20 breadcrumbs, plus aggregate stats (count, first/last seen).

{
  "project": "Gramax-PROD",
  "platform": "tauri",
  "errorId": "...",
  "errorClass": "...",
  "message": "...",
  "count": 412,
  "firstSeen": "...",
  "lastSeen": "...",
  "topFrame": "...",
  "stacktrace": [...],
  "latestEvent": {
    "id": "...",
    "received": "...",
    "context": "...",
    "device": {...},
    "app": {...},
    "user": {...},
    "request": {...},
    "metaData": {"user": {"errorDisplayed": true}, "logic_props": {...}, ...},
    "breadcrumbs": [...]
  },
  "url": "..."
}

fix — mark resolved + comment (write)

Before touching code: run the superpowers:systematic-debugging skill. It enforces reproduction → minimal failing case → root-cause hypothesis → targeted patch, instead of guessing from the stacktrace. Use show --error <id> to gather breadcrumbs, request, and metaData before forming hypotheses; that data is what feeds the debugging skill.

Important: marking an error fixed in Bugsnag does not fix the bug. The CLI just changes the error's state and posts a comment. The actual code change must reach the latest release branch via one of:

1. GitLab MR targeting the latest release/* branch — open MR with the patch directly against the release branch.
2. Commit to develop → cherry-pick to the latest release/* branch — land on develop first, then git cherry-pick <sha> onto the release branch (or open a cherry-pick MR).

Only call fix after the change is merged / cherry-picked. The --comment should reference the MR or commit (e.g. "fixed in !1234, cherry-picked to release/2026.6").

bun .claude/skills/bugsnag/scripts/bugsnag.ts fix \
  --error <id> \
  --project <name> \
  --comment "<text>" \
  [--release-stage production] \
  --yes

--yes required. Without it CLI prints what it would do and exits 2.

{
  "ok": true,
  "errorId": "5f...",
  "project": "Gramax-PROD",
  "operations": ["fix", "comment"],
  "comment": {"id": "...", "message": "fixed in 2026.6.0"},
  "url": "..."
}

On failure: {"ok": false, "step": "fix"|"comment", "status": <code>, "error": "..."} + non-zero exit.

comment — post comment only (write)

bun .claude/skills/bugsnag/scripts/bugsnag.ts comment \
  --error <id> \
  --project <name> \
  --message "<text>" \
  --yes

Common queries

After running stats --pretty > /tmp/bs.json:

# Top 5 Gramax-PROD tauri errors visible to users
jq '.events | map(select(.project=="Gramax-PROD" and .platform=="tauri" and .countDisplayed>0)) | .[:5]' /tmp/bs.json

# Impact >= 5
jq '.events | map(select(.impact>=5))' /tmp/bs.json

# Just error IDs + URLs for triage
jq '.events | map({errorId, url, impact, count})' /tmp/bs.json

Rate limits + timing

Bugsnag SaaS rate limit ~100 req/min. CLI batches per-error fetches in chunks of 8 with 700ms throttle. Typical stats --top 20 across 2 projects ≈ 40 errors × ≤2 enrich calls ≈ 60–80 requests, well within the limit. Use --no-stack --no-split to cut all enrich calls.

Output format

stdout = JSON only. stderr = human progress (project discovery, page counts, warnings). Pipe stdout into jq safely.

Exit codes:

• 0 — success
• 1 — runtime error (network/auth/parse)
• 2 — usage error (bad flags, missing --yes on write)
• 3 — Bugsnag API rejection or error not found