Claude Code Debug Mode

Debug Mode Skill (Claude Code + Codex + Gemini CLI)

A hypothesis-driven debugging skill for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Codex, and [Gemini CLI](https://github.com/google-gemini/gemini-cli). Instead of blindly guessing fixes, it instruments your code with runtime logs, generates multiple hypotheses, and iteratively narrows down the root cause — with you in the loop.

Inspired by [Cursor's Debug Mode](https://www.cursor.com/blog/introducing-debug-mode).

How It Works

Bug Report → Hypotheses → Instrument Code → Reproduce → Analyze Logs → Fix → Verify → Clean Up

1. Understand — Gathers context about the bug (expected vs actual behavior, repro steps)
2. Hypothesize — Generates 3–5 testable hypotheses about root causes
3. Instrument — Adds targeted debug logging wrapped in #region DEBUG blocks
4. Reproduce — You trigger the bug while logs are collected to .claude/debug.log
5. Diagnose — Maps log output to hypotheses, confirms or rules out each one
6. Fix — Writes a minimal, targeted fix (not a refactor)
7. Verify — You confirm the fix works; if not, the cycle repeats
8. Clean up — Removes all instrumentation, leaving a clean diff

Install

One-liner (Claude Code)

# macOS / Linux / Windows (Git Bash / MSYS2)
mkdir -p ~/.claude/skills && git clone https://github.com/doraemonkeys/claude-code-debug-mode.git ~/.claude/skills/claude-code-debug-mode

# Claude Code discovers skills only ONE directory level under ~/.claude/skills/
# (it does not recurse), but this repo keeps SKILL.md inside debug-mode/. Lift that
# folder up one level, otherwise the skill silently won't load:
mv ~/.claude/skills/claude-code-debug-mode/debug-mode ~/.claude/skills/debug-mode
rm -rf ~/.claude/skills/claude-code-debug-mode

**Why the extra step (Claude only):** Codex and Gemini scan `skills/` recursively, so they find `claude-code-debug-mode/debug-mode/SKILL.md` on their own. Claude Code look