Debugging Tips

Essential debugging techniques and tools for troubleshooting Claude Code issues

Doctor Command

Use /doctor for diagnostics when troubleshooting Claude Code issues. This built-in command checks your setup and identifies common problems.

See the CLI Reference for more information on diagnostic commands.

Background Tasks for Debugging

Always ask Claude to run the terminal (you want to see logs of) as a background task for better debugging visibility.

Background tasks allow you to:

• Monitor logs in real-time
• See server output while Claude continues working
• Catch errors that might be hidden in synchronous execution

Browser Debugging with MCP

Use MCP servers to let Claude see Chrome console logs on its own:

• Claude in Chrome
• Playwright MCP
• Chrome DevTools MCP

These tools enable Claude to:

• Inspect console errors directly
• Debug browser-based applications
• Automate testing and debugging workflows

See the Browser Automation MCP Comparison for detailed analysis of these tools.

Visual Debugging

Provide screenshots of the issue when reporting visual bugs or UI problems. Claude can analyze images to better understand what’s wrong.

Cross-Model QA

Use a different model for QA — e.g., Codex for plan and implementation review. This provides a fresh perspective on your code.

Common Debugging Workflows

Server Issues

1. Run the server as a background task
2. Ask Claude to check the logs
3. Use MCP if browser-based debugging is needed
4. Provide screenshots of browser errors

Build Errors

1. Run /doctor to check for environment issues
2. Review error messages carefully
3. Compact context if approaching limits
4. Use plan mode for complex multi-step fixes

Permission Issues

Check /permissions to see what’s allowed. Use wildcard syntax for broader permissions:

• Bash(npm run *)
• Edit(/docs/**)

Alternatively, use /sandbox to reduce permission prompts with file and network isolation.