Key-free tooling for Snag Maps — a Happy Path → Failure Map for a PRD, spec, or code change. A Snag Map applies FMEA-style reasoning (the failure-analysis discipline from aerospace and manufacturing) to a document or a diff and surfaces the failure modes a normal review tends to miss, as an interactive graph you can commit to git and review like any other artifact.
The map itself is generated by a coding-agent skill running inside your own agent
(Claude Code, Codex, …), which emits a failure-map/v1 JSON. The CLI is
key-free: it holds no provider API key and makes no LLM call. It ingests that
JSON, validates it, serves a local read-only viewer, and can optionally push a
committed map to a backend with your own bearer token.
This is a pnpm workspace of four packages:
| Package | What it is |
|---|---|
@snag-run/cli |
The snag command: map ingest, map validate, view, push. |
@snag-run/core |
Deterministic core — the failure-map/v1 schema plus severity, anchoring, lint, and reconcile. Browser-safe (zod only). |
@snag-run/renderer |
Framework-agnostic Cytoscape viewer for a Snag Map. |
@snag-run/engine |
Map-generation core (schema + engine). |
npm install -g @snag-run/cli
snag --helpRequires Node.js >= 20.
# 1. In your coding agent, run a map-generating skill over a PRD, a file, or a
# named capability. It produces a failure-map/v1 JSON using the agent's own
# read-only tools — no provider key configured in snag.
# 2. Bring that JSON in — snag validates it, derives the committed path from the
# map's own subject, and reconciles node ids against the prior snapshot:
snag map ingest path/to/skill-output.json
# 3. Open the interactive viewer
snag viewSee packages/cli/README.md for the full command and
flag reference.
pnpm install
pnpm build # tsc --build across the workspace
pnpm test # vitest
pnpm lint # eslintsnag was meant to become a product: a hosted service around Snag Maps, with a backend, collaboration, and a paid tier. It deliberately did not get there. Three findings, in the order they landed:
The ICP stayed uncertain. I could not name a specific customer who felt this problem acutely enough to adopt a dedicated tool. Every candidate was a maybe, and a product whose customers are all maybes is not a product yet.
Thinking hard about the ICP weakened the value prop. The closer I looked at who would actually buy this, the more the pitch dissolved. The teams disciplined enough to want structured failure-mode analysis were largely the ones who could already get most of it from a careful reviewer and a good prompt. The hosted layer was not adding enough on top of that to be worth paying for.
The experiments showed the skill held most of the value. I ran a pre-registered ablation comparing the full product machinery against a plain skill approach: an FMEA lens the coding agent runs itself, no service, no graph store. The skill recovered most of the catches; the extra infrastructure earned little. When your own experiment says the cheap version is about as good, that is a result worth trusting, not a setback to argue with.
So I collapsed the product surface and kept what actually carried the value: the snag-fmea review skill and this CLI, both open-sourced as an honest record. The map generator, the backend, and the paid plans are parked.
That is why a couple of surfaces here are dormant:
snag pushtargets a hosted backend that is not running, so the push path and itsSNAG_API_KEY/SNAG_BACKEND_URLenv vars are inert. The ingest / validate / view path is fully local and needs no backend.- Any
snag.runlinks may 404 until (or unless) the site is up.
This repo stands as the artifact: a working, key-free map toolchain, and a decision to stop building around it the moment the evidence said the skill was the product.
Apache-2.0 © David Taing. See LICENSE.