CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

stackpack-debug

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.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Failed to scan

The risk profile of this skill

SKILL.md
Quality
Evals
Security

stackpack-debug — Runtime DevTools for AI Agents

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.

CRITICAL: Read debug://status FIRST

Before ANY investigation, read the debug://status resource. It's a live situation report containing:

  • Full terminal output (not just errors — app state logs too)
  • Browser console (all logs, errors, warnings, network failures)
  • Build errors (Vite, tsc, webpack, ESLint)
  • Runtime errors (server-side unhandled rejections, stack traces, connection errors — not visible in browser devtools)
  • Configuration state (AI provider settings, model selection, env file values with persistence tracking)
  • TypeScript errors (proactive tsc --noEmit)
  • Git activity (recent commits, uncommitted changes)
  • Tauri logs (auto-discovered)
  • Active debug sessions

This is updated every 5 seconds. It tells you what's happening RIGHT NOW without any tool call.

Quick Error Check: debug://errors

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.

When to Activate — MANDATORY

You MUST use the toolkit when the user mentions ANY of these:

  • "bug", "error", "issue", "warning", "crash", "panic", "exception"
  • "fix", "debug", "investigate", "diagnose", "troubleshoot"
  • "broken", "fails", "doesn't work", "wrong", "unexpected"
  • "review errors", "review issues", "check the app", "what's wrong"
  • "layout", "overlap", "misaligned", "cut off", "hidden", "clipped"
  • "flicker", "flash", "glitch", "visual", "looks wrong", "UI bug"
  • "slow", "laggy", "performance", "takes too long", "freezes"
  • "test failure", "test fails", "tests broken"
  • User describes something that should work but doesn't
  • User asks to review, check, or audit the running app
  • User pastes a stack trace, error message, or console output
  • User references console errors, build warnings, or compiler output
  • User says "it crashes", "it panics", "it shows an error"
  • "resets", "setting", "config", "provider", "wrong endpoint", "wrong model"

Do NOT use only when:

  • User asks for a brand new feature with no existing bug
  • User asks to refactor working code with no problems
  • The fix is an obvious typo the user already identified

Why This Beats Manual File Reading

debug_investigate returns in ONE call what would take 20+ file reads:

What you getManual approachToolkit
Source code at crash siteRead 3-5 files guessing50-line window around exact line
Runtime errorsAsk user to pasteAuto-captured from terminal
Server-side errorsInvisible (console.error in API routes)Parsed from stderr with stack traces
Browser consoleCannot accessAll console.log/warn/error
Config stateRead .env files manuallyAuto-reads env files with persistence tracking
TypeScript errorsRun tsc yourselfAuto-runs tsc --noEmit
Git changesRun git diff yourselfActual diff content included
Build errorsCheck terminal yourselfParsed and structured
Past solutionsDon't existCross-session memory with confidence
Visual stateCannot seeScreenshot + 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.

The Workflow

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-investigation

Shortcuts:

  • triage: "trivial" → apply fixHint directly
  • proactiveSuggestion with >80% confidence → apply directly
  • visualHint.isVisualBug → use debug_visual for screenshots

Tool Reference

debug_investigate

Start 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: [] }

debug_visual

Screenshot, element inspection, annotated view, before/after comparison. Requires Ghost OS.

{ sessionId, action: "screenshot" | "inspect" | "annotate" | "compare" }

debug_perf

Lighthouse performance profiling with before/after comparison.

{ sessionId, url: "http://localhost:1420", phase: "before" | "after" }

debug_hypothesis

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.

debug_recall

Search past debug sessions for similar bugs.

{ query: "timestamps overlap in timeline", limit?: 5 }

debug_trace_origin

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).

debug_patterns

Detect systemic issues across all past sessions. Finds recurring errors, hot files, regressions.

debug_instrument

Add tagged debug logging. Supports JS/TS, Python, Go, Rust.

{ sessionId, filePath, lineNumber, expression: "state.items.length" }

debug_capture

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" }

debug_verify

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 }

debug_cleanup

Remove instrumentation and save diagnosis to memory.

{ sessionId, diagnosis?: "root cause was..." }

debug_session

Lightweight session status.

debug_setup

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 registry
  • update — update stackpack-debug to latest, then restart Claude Code

Note: stackpack-debug auto-upgrades in the background on every startup. Manual updates are rarely needed.

Network Awareness

The toolkit detects running dev servers and maps their network connections automatically. This works in ALL modes — even without spdg serve.

What it shows:

  • Dev server port, PID, and process name
  • Inbound connections (browsers connecting to the server)
  • Outbound connections (server connecting to Ollama, Postgres, Redis, etc.)
  • Missing connections (config expects a service but no connection exists)

When to look at it:

  • Timeout errors → check if the server has outbound connections
  • "No response" → check if requests reach the server (inbound) and leave it (outbound)
  • Wrong provider → check which service the server is actually connecting to

Rules

  1. Read debug://status BEFORE investigating. It's free context.
  2. ALWAYS call debug_investigate for any bug. Even layout bugs, visual issues, or "review the app" requests.
  3. Never manually explore code for debugging when the toolkit is available. The toolkit sees runtime state that files cannot show.
  4. Read nextStep in every response — it tells you what to do.
  5. If proactiveSuggestion with >80% confidence → apply directly, then verify.
  6. For visual bugs, pass suspect file paths in files AND use debug_visual.
  7. ALWAYS run debug_verify before claiming a fix works.
  8. Pass sessionId from debug_investigate to all subsequent calls.

Redirect & state-conditional bugs — debug the ORIGIN, not the destination

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.

  1. The symptom names the wrong suspect. A redirect to /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.
  2. "Works locally, breaks in prod" = state-dependent, not a code bug. Same code, different behavior between environments means the cause is whatever differs by state — usually auth (signed-in locally, anonymous in prod) or data (a record that exists locally but not for the affected user). Ask: what code path runs only in the broken state? and inspect the relevant DB record for that state.
  3. If you've edited the same file 3+ times without resolving it, stop. 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."

The Loop — state-aware debugging

When stackpack-state is connected (via attachTelemetry or autoAttach), debug receives:

  • Every mutation, with prev/next diffs and actor attribution.
  • Every gate flip and when condition flip.
  • Presence enter/leave events.
  • Causal links via the 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.
  • Background detectors:
    • 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.

Enabling in dev

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.

Repository

stackpackdev/debug

Path

SKILL.md

Last updated
First committed

Is this your skill?

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.