Diagnostic Tools and Session Debugging

Something broke. Claude Code is ignoring your CLAUDE.md, using the wrong model, burning through your context window on nonsense. You could stare at the screen and wonder what went wrong. Or you could actually diagnose it.

Most people never find these tools. Which is a shame, because they've been there the whole time.

The Built-In Toolkit

/doctor runs a health check on your entire Claude Code installation. Preflight checklist. Verifies your installation type and version, checks whether auto-update is working, validates settings files for syntax errors, tests MCP server connections, flags keybinding conflicts, warns about context window usage, and catches plugin or agent loading errors. If something is fundamentally janky with your setup, /doctor will find it.

/debug is a bundled skill that kicks off systematic debugging. Claude Code walks through a structured process to identify what went wrong in your current session. Not a generic "fix my code" tool. Specifically for diagnosing problems with Claude Code itself.

/insights generates a session analysis report. What project areas you worked on, your interaction patterns, friction points, overall session health. Really useful for understanding why a session felt unproductive.

/security-review analyzes pending changes for security vulnerabilities before you commit. Scans diffs for hardcoded secrets, injection risks, common vulnerability patterns.

/stats visualizes daily usage, session history, streaks, model preferences. Good for tracking how much you're actually using Claude Code and which models you lean on.

/context, /export, /feedback, /bug round out the toolkit. Context window visualization, conversation export as plain text, and direct issue reporting to the Claude Code team.

Debug Flags

Two command-line flags give you deeper visibility than the slash commands.

--debug enables debug mode at launch. Internal logs and system-level information that's normally hidden becomes visible.

claude --debug

Filter by category with a comma-separated list:

claude --debug "api,hooks"

Exclude noisy categories by prefixing with !:

claude --debug "!statsig,!file"

When you suspect a specific subsystem is misbehaving, this is how you zero in on it without drowning in noise.

--verbose shows full turn-by-turn output. Every tool call, every response, every decision. Heavier than --debug but gives you complete transparency.

claude --verbose

Try it

Run /doctor right now. Read every line of output. If everything passes, great. If something fails, you just saved yourself hours of confusion.

Then try:

claude --debug "api"

Start a short session and watch the API-level logs. You'll see which model is being called, what parameters are being sent, how responses come back. Fastest way to verify that your configuration is doing what you think it is.

Which Tool When

Knowing these exist is the easy part. Knowing which one to reach for is what actually saves time.

Setup feels broken. /doctor. Always start here when things feel fundamentally off.

Claude Code doing something weird mid-session. /debug. Systematic walkthrough of what might be going wrong in the current context.

Session felt slow or frustrating. /insights at the end. Highlights friction points you might not have noticed in the moment.

About to commit AI-generated code. /security-review. Takes seconds. Catches accidentally exposed API keys, SQL injection vulnerabilities. Just build it into your flow.

Want to understand usage patterns. /stats.

Claude Code forgetting things. /context. If the grid is packed, you know exactly why responses are degrading.

Need to see what Claude Code is doing internally. --debug with category filters for targeted investigation, --verbose for the full picture.

Something is genuinely broken and not your fault. /bug. Include reproduction steps and /doctor output.

A solid routine: /doctor once at the start of every new project. /context periodically during long sessions. /security-review before committing AI-generated code. Most problems get caught before they turn into real headaches.