Runtime DevTools for AI agents. Captures terminal output, browser console, build errors, TypeScript errors, git diffs, and screenshots from the running app. MANDATORY for: any bug, error, issue, warning, crash, panic, layout problem, visual glitch, wrong behavior, performance issue, test failure, reviewing the running app, checking app health. Read debug://status FIRST — it's a live situation report. Read debug://errors for errors only. Call debug_investigate for deep analysis.
81%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Failed to scan
The risk profile of this skill
The toolkit captures what's actually happening at runtime — terminal output, browser console, build errors, runtime errors (server-side console.error, unhandled rejections, stack traces), TypeScript errors, git diffs, configuration state, screenshots, and cross-session memory. It gives you the same signals a developer sees in browser DevTools and terminal.
Before ANY investigation, read the debug://status resource. It's a live situation report containing:
tsc --noEmit)This is updated every 5 seconds. It tells you what's happening RIGHT NOW without any tool call.
Read debug://errors when you only need errors. Compact, deduplicated view of errors/warnings from ALL sources (terminal, browser, build, TypeScript). No noise, no app logs — just signal.
You MUST use the toolkit when the user mentions ANY of these:
Do NOT use only when:
debug_investigate returns in ONE call what would take 20+ file reads:
| What you get | Manual approach | Toolkit |
|---|---|---|
| Source code at crash site | Read 3-5 files guessing | 50-line window around exact line |
| Runtime errors | Ask user to paste | Auto-captured from terminal |
| Server-side errors | Invisible (console.error in API routes) | Parsed from stderr with stack traces |
| Browser console | Cannot access | All console.log/warn/error |
| Config state | Read .env files manually | Auto-reads env files with persistence tracking |
| TypeScript errors | Run tsc yourself | Auto-runs tsc --noEmit |
| Git changes | Run git diff yourself | Actual diff content included |
| Build errors | Check terminal yourself | Parsed and structured |
| Past solutions | Don't exist | Cross-session memory with confidence |
| Visual state | Cannot see | Screenshot + DOM via Ghost OS |
Never manually grep/read files for debugging when the toolkit is available. The toolkit sees runtime state; file reading sees static code.
1. Read debug://status → see what's happening right now
2. debug_investigate → deep analysis with runtime context + memory
3. debug_hypothesis → log what you think the root cause is and why
4. debug_visual → screenshot/DOM if visual bug
5. debug_perf → profile if performance issue
6. (apply fix)
7. debug_verify → confirm fix works (auto-saves to memory)
3+ failures → escalation triggers re-investigationShortcuts:
triage: "trivial" → apply fixHint directlyproactiveSuggestion with >80% confidence → apply directlyvisualHint.isVisualBug → use debug_visual for screenshotsStart here. Always. Returns: error classification, source code (50-line window), runtime output (terminal + browser + Tauri logs), server-side runtime errors (unhandled rejections, stack traces), configuration state (provider settings, env file values), TypeScript errors, git diff content, build errors, past solutions, visual state.
# Runtime error
{ error: "<stack trace>" }
# Layout/behavior bug
{ error: "timestamps overlap in timeline", files: ["src/Timeline.tsx"] }
# Review running app
{ error: "Review all errors and warnings", files: [] }Screenshot, element inspection, annotated view, before/after comparison. Requires Ghost OS.
{ sessionId, action: "screenshot" | "inspect" | "annotate" | "compare" }Lighthouse performance profiling with before/after comparison.
{ sessionId, url: "http://localhost:1420", phase: "before" | "after" }Log a hypothesis before attempting a fix. Creates an auditable investigation trail. Update status to confirmed or rejected after testing.
# Create new hypothesis
{ sessionId, hypothesis: "The null check is missing because req.user is undefined when auth skips" }
# Update existing hypothesis
{ sessionId, hypothesisId: "hyp_abc", status: "rejected", evidence: ["error persists after adding null check"] }After 2+ rejected hypotheses, the tool suggests checking debug_patterns for systemic issues.
Search past debug sessions for similar bugs.
{ query: "timestamps overlap in timeline", limit?: 5 }Find what emits a redirect/navigation to a path — not the page it points at. For "redirects to /X" bugs where you keep editing /X without fixing it.
{ symptom: "/sign-in" } // or "anon user redirects to /sign-in"Statically scans for every redirect()/auth-guard (requireUserId, auth.protect, RedirectToSignIn) that targets the path, then traces which code calls those guards — flagging auto-fired call sites (on mount, useEffect(…, []), auto-opening components) that run with no user click and so don't look like an auth flow. Auto-fired origins are ranked first; they're the usual culprit. debug_investigate runs this automatically when the error text looks like a redirect (see symptomOrigin in its output).
Detect systemic issues across all past sessions. Finds recurring errors, hot files, regressions.
Add tagged debug logging. Supports JS/TS, Python, Go, Rust.
{ sessionId, filePath, lineNumber, expression: "state.items.length" }Run a command and capture output, or drain buffered events. SessionId is optional — omit to read console output directly.
{ command?: "npm test", source?: "browser", filter?: "SCROLL-DEBUG", level?: "error" }Confirm a fix works. Auto-saves to memory on pass. After 3+ failed fix attempts, triggers an escalation that forces re-investigation — your mental model of the bug is likely wrong.
{ sessionId, command: "npm test", expectNoErrors?: true }Remove instrumentation and save diagnosis to memory.
{ sessionId, diagnosis?: "root cause was..." }Lightweight session status.
Check/install integrations, check for updates, or update stackpack-debug.
{ action: "check" | "install" | "connect" | "disconnect" | "check-update" | "update" }check-update — compare installed version against npm registryupdate — update stackpack-debug to latest, then restart Claude CodeNote: stackpack-debug auto-upgrades in the background on every startup. Manual updates are rarely needed.
The toolkit detects running dev servers and maps their network connections automatically. This works in ALL modes — even without spdg serve.
What it shows:
When to look at it:
debug://status BEFORE investigating. It's free context.debug_investigate for any bug. Even layout bugs, visual issues, or "review the app" requests.nextStep in every response — it tells you what to do.proactiveSuggestion with >80% confidence → apply directly, then verify.files AND use debug_visual.debug_verify before claiming a fix works.sessionId from debug_investigate to all subsequent calls.When a symptom is "redirects/navigates to /X", "/X loads instead of the page", or "works locally but breaks in prod", do NOT start by editing /X or the component the redirect lands on. That's the destination — almost never the cause.
/sign-in makes the auth
UI look central. The real emitter is usually a guard (requireUserId() →
redirect('/sign-in')) called from somewhere non-obvious — often auto-fired on
mount (a useEffect(…, []), an auto-opening paywall/dialog, a server action that
runs without a click). Run debug_trace_origin({ symptom: "/sign-in" }) to find it.debug_investigate will flag this as fileOrbiting. Editing one file repeatedly
while the symptom persists means the cause is elsewhere. Switch from "what's wrong in
this file" to "what runs unprompted for the affected state that I haven't looked
at yet."When stackpack-state is connected (via attachTelemetry or autoAttach), debug receives:
when condition flip.causedBy field — debug walks chains of cause-and-effect, not just a flat log.This unlocks:
debug://state — current state of every store: latest next, all gates, all when conditions, last actor.debug://timeline — interleaved state events with terminal/console/network signals, in chronological order with causal links visible.debug_investigate — automatically includes recentMutations, lastActor, affectedStores, and the causalChain when state telemetry is active.gate.flicker — three flips of the same gate within 500ms.presence.leak — item left a tracked array but never re-entered or fully removed within 5 seconds.effect.cascade — chain of more than 5 effect-driven mutations linked by causedBy.Detector warnings appear in debug://status and debug://errors whenever they fire, and also flow into debug://timeline.
In a Vite-based project, add to vite.config.ts:
import { stackpackDebug } from 'stackpack-debug/vite-plugin'
export default {
plugins: [
stackpackDebug({ stateTelemetry: true }),
],
}Or call autoAttach() directly in your app entry — see the stackpack-state SKILL.md for the alternative.
stackpackdev/debug
SKILL.md
794a9b3
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.