devdump

Built for non-developers building with AI. When your app breaks mid-build, the hardest part isn't fixing it. It's giving your AI coding tool enough context to actually help. Most sessions balloon from 3 turns to 10 because you describe symptoms instead of sharing what's actually broken.

devdump fixes that. Run it from your project root, paste your console error, and it collects everything relevant: the error, ranked hotspot files, build state, git context, and config. You get a single markdown block on your clipboard. Paste it as your first message into Claude Code, Codex, Cursor, or any AI coding tool. Full context on turn 1.

npm install -g devdump-cli   # recommended for regular use
npx devdump-cli              # or run without installing

---

How it works

1. You paste your console error. devdump asks for it first, redacts any secrets, and extracts file references from the stack trace. If you skip it, devdump asks "What's happening instead?" so the output is never blank.
2. You confirm the build check. devdump asks before running npm run build (takes ~30s). Skip it for instant collection.
3. devdump auto-collects. Checks git state, scans recent commits for hotspot ranking, and checks your env keys.
4. You get a clipboard-ready markdown block. Paste it into Claude Code, Codex, Cursor, or any AI coding tool as your opening message.

---

Flags

devdump                # full interactive run
devdump --no-primer    # omit the embedded Claude instruction comment
devdump --verify       # re-run after a fix, replaces "What's broken" with "Post-fix check"

---

Build hook

Install a post-build hook so devdump runs automatically when your build fails:

npx devdump-cli hook install   # adds devdump to your postbuild script
npx devdump-cli hook remove    # removes it

Works with any project that has a package.json.

---

MCP integration (optional)

Register devdump as an MCP server so Claude Code can pull diagnostic context directly, without the clipboard step.

npx devdump-cli mcp install   # adds devdump to ~/.claude.json, then restart Claude Code
npx devdump-cli mcp remove    # removes it

Once installed, Claude Code calls devdump_snapshot automatically when you describe a bug. Same output as the CLI, just Claude-triggered instead of you-triggered.

devdump is still the primary method. MCP is optional.

---

What it collects

What	How	Why
Console error or description	You paste it	The single most useful piece of context for debugging
Hotspots	Ranked top 3 files: stack trace first, recent commits second, config changes third	Surfaces the most likely culprits immediately
Code context	+/- 5 lines around the top hotspot	Gives Claude the exact code without a full file read
Signals	3 diagnostic rules applied to collected data	Gives Claude a starting interpretation
Build status	Runs npm run build (opt-in), captures first error line	Tells Claude whether the problem is compile-time or runtime
Env key presence	Checks Firebase keys by name, never reads values	Catches missing or misconfigured env vars without exposing secrets
Git state	Branch, uncommitted file count, last commit message	Rules out "did you save / are you on the right branch" questions
Environment	Node version, npm version, detected framework	Eliminates version mismatch guessing

---

Output format

Section order is fixed: What's broken, Files likely involved, Hotspots, Signals, Build, Config, Git, Environment. Target is 30 to 35 lines. Code context is dropped if the total would exceed 35 lines.

Sample output

## devdump

### What's broken
TypeError: Cannot read properties of null (reading 'uid')
    at src/AuthContext.js:42

### Files likely involved
src/AuthContext.js:42

### Hotspots
1. src/AuthContext.js:42 (from error)
2. src/App.js (recent commit)
3. firebase.json (config change)

`src/AuthContext.js:42`
40  const user = getAuth().currentUser;
41  if (!user) return null;
42  > return user.uid;
43  const db = getFirestore();
44  return db.collection('users');

### Signals
- Build clean, error at runtime → likely frontend logic issue
- Stack trace + clean build → focus on src/AuthContext.js:42

### Build
✅ clean

### Config (Firebase + Vite)
- VITE_FIREBASE_API_KEY: ✓
- VITE_FIREBASE_AUTH_DOMAIN: ✓
- VITE_FIREBASE_PROJECT_ID: ✓ → `my-app-prod`
- VITE_FIREBASE_STORAGE_BUCKET: ✗ missing

### Git
Branch: `main` | 3 uncommitted files | Last: "fix: auth flow" (2h ago)

### Environment
Node v20.11.0 | npm 10.2.4 | vite

<!-- Claude: read every file before editing. No exceptions. -->

---

Signals

Condition	Signal
Build clean + error present	Build clean, error at runtime → likely frontend logic issue
Any Firebase config key missing	Missing Firebase key(s) → config incomplete
Stack trace present + build clean	Stack trace + clean build → focus on [files]

---

Supported

• Frameworks: Vite, Create React App, Next.js
• Firebase: auto-detected from package.json, firebase.json, or src/firebaseConfig.js
• OS: macOS (primary), Linux, Windows
• Node: 18+

---

Out of scope

• Watch mode
• Python, Django, Flask, or any non-JS stack
• Firebase emulator detection
• Monorepos or multi-framework projects
• Snapshot history or diff between runs
• Any AI/LLM integration (devdump collects context; diagnosis is your AI tool's job)

---

Security

• Secret redaction. Console error input is scanned before output. Firebase API keys (AIza*), Bearer tokens, sk- keys, long base64 strings, and password= / secret= / token= patterns are replaced with [REDACTED].
• Env values never exposed. devdump checks whether keys are present, not their values. The only exception is Firebase project ID, which is low-sensitivity and high diagnostic value.
• Read-only. devdump never writes to your filesystem.
• Zero network requests. Everything runs locally.
• No telemetry. Nothing is logged or sent anywhere.