snapfail Documentation

snapfail is a context capture layer for AI-assisted debugging. When your app crashes in the browser, snapfail captures the full evidence and packages it so your AI agent (Claude Code, Cursor, Copilot) can diagnose the root cause directly.

How it works

Quick start

One command installs and configures everything.

1. Install

# npm
npm install -g @snapfail/cli

# or bun
bun add -g @snapfail/cli

2. Initialize in your project

snapfail init

snapfail init does everything automatically:

• Detects your framework (Astro, Vite, Next.js)
• Opens the browser for authentication
• Injects the browser SDK into your framework config
• Writes SNAPFAIL_PROJECT_KEY to your .env
• Generates .agents/skills/snapfail/SKILL.md for your AI agent

3. Ask your AI to investigate

# List unresolved incidents
snapfail incidents

# Full diagnosis for an incident
snapfail explain <id>

snapfail init

Sets up snapfail in your project. You only need to run this once.

snapfail init

What it does

snapfail incidents

Lists incident groups for your project.

snapfail incidents [options]

Options

Example output

{"groups": [
  {
    "id": "inc_8f2a",
    "title": "TypeError: cannot read 'total' of undefined",
    "severity": "critical",
    "status": "unresolved",
    "count": 1284,
    "affectedUsers": 312,
    "lastSeen": "2025-06-01T18:30:00Z",
    "environments": ["prod"]
  }
]}

snapfail incident <id>

Detail for a group: summary + representative sample.

snapfail incident <id> [--sample <n>] [--json]

Options

snapfail explain <id>

The primary command for AI diagnosis. Emits the full structured evidence from up to 3 samples, ready for the LLM to reason about the root cause.

snapfail explain <id>

The output includes:

• group — normalized title, severity, count, affected users
• samples[].stackFrames — call stack at error time, frames from your app highlighted
• samples[].consoleEntries — console logs before the error
• samples[].networkEntries — network requests with status, duration, and headers (no auth)
• samples[].timeline — sequence of user interactions
• samples[].device — user agent, viewport, language

snapfail suppress

Manage suppression rules to filter known noise (browser errors, bots, healthchecks).

# List active rules
snapfail suppress list

# Create a rule
snapfail suppress add --field message --pattern "ResizeObserver loop*"

# Delete a rule
snapfail suppress delete <rule-id>

Available fields

Browser SDK

The SDK runs in the end user's browser. It captures errors in real time using four event-driven collectors that write to an in-memory ring buffer.

When an error occurs, the SDK freezes the buffer, assembles the IncidentSample, scrubs sensitive data in the browser before sending, and transmits to the cloud endpoint.

Framework adapters

snapfail init installs the correct adapter automatically. You can also do it manually:

Astro

import { defineConfig } from 'astro/config';
import snapfail from '@snapfail/astro';

export default defineConfig({
  integrations: [snapfail()]
});

Vite

import snapfail from '@snapfail/vite';

export default { plugins: [snapfail()] };

Next.js

const snapfail = require('@snapfail/next');

module.exports = snapfail({ /* next config */ });

Configuration

The SDK is configured with the project key and environment options.

snapfail("proj_xxxxxxxxxxxxxxxxx", {
  endpoint: "https://app.snapfail.com",  // ingest URL
  env: "prod",                            // "dev" | "prod"
  replay: true,                           // DOM replay (default: true)
  storage: false,                         // storage snapshot (default: false)
});

Incidents & groups

snapfail groups occurrences of the same error by fingerprint — a deterministic signature derived from the normalized message + stack trace.

Fingerprint normalization

Sampling

snapfail uses reservoir sampling with diversity to keep a maximum of 50 samples per group. Instead of saving the first N identical occurrences, it prioritizes:

• Samples from different time periods
• Different environments (dev vs prod)
• Different devices and browsers

This ensures that when analyzing samples, the LLM sees variety — not 50 identical occurrences from the same user on the same device.

Privacy & scrubbing

Scrubbing happens in the end user's browser, before anything leaves the network. No sensitive data ever reaches the server.

Network headers — full drop

Query params — value replaced with [redacted]

Console

• JWTs (eyJ...) → [token]
• API keys with prefixes (sk-, pk_live_, Bearer) → [api-key]

Replay / DOM

• input[type=password] → value ●●●●●●
• Inputs with name/id in password|token|secret|card|cvv|ssn → masked
• Card number pattern → [card]

SKILL.md

snapfail init automatically generates .agents/skills/snapfail/SKILL.md — a context file your AI agent reads so it can use snapfail without you having to explain anything.

It contains:

• Project summary (detected framework, routes, endpoints)
• Incident format and how to interpret it
• CLI commands and when to use them
• The project-specific fix prompt pattern

To activate it in Claude Code, import the skill from your CLAUDE.md:

import .agents/skills/snapfail/SKILL.md

Reading evidence

When your AI runs snapfail explain <id>, it receives structured evidence from up to 3 samples. Here's how to interpret each field:

Fix prompts

After diagnosing, snapfail explain generates a fix prompt ready to paste into Cursor, Claude Code, or your preferred agent.

In Cart.jsx:42, the component reads `cart.total` assuming `cart`
always exists, but `/api/cart` can respond with an empty body.

Fix:
1. Guard the access with `cart?.total ?? 0`
2. Add empty-state handling before rendering the checkout
3. Verify the `/api/cart` contract — it should return `{ items: [] }`
   instead of an empty body when the cart is empty

The fix prompt includes:

• Exact file and line of the error
• Technical root cause
• Concrete fix steps
• API contract context if applicable