Debug Mode Skills

This tool recreates Debug Mode found in other popular agentic code editors.

Debug Mode forces a disciplined debugging process:

1. Hypothesize - Generate multiple specific theories about the bug's cause
2. Start Logging Server - Spins up a lightweight server to collect logs based on each hypothesis
3. Instrument - Add targeted logging to test each hypothesis
4. Reproduce - You trigger the bug while logs capture what actually happens
5. Analyze - Confirm or reject hypotheses based on runtime evidence
6. Fix - Implement the fix with confidence
7. Verify - Prove the fix works with fresh logs

Installation

Option 1: Install as portable skills

The repo is packaged as a skills.sh bundle and can be installed into multiple agents from the same source.

Install into Codex:

bunx skills add https://github.com/mikecfisher/agent-debug-mode --agent codex -y

Install into Claude Code:

bunx skills add https://github.com/mikecfisher/agent-debug-mode --agent claude-code -y

Install from a local checkout during development:

bunx skills add /absolute/path/to/agent-debug-mode --agent codex -y
bunx skills add /absolute/path/to/agent-debug-mode --agent claude-code -y

The bundle exposes four skills:

• debug-mode
• debug-reproduced
• debug-fixed
• debug-auto

The skill runtime is self-contained. Each installed skill carries its own helper scripts, so it does not depend on CLAUDE_PLUGIN_ROOT or repo-root script paths.

Option 2: Claude plugin marketplace

First, add the marketplace:

/plugin marketplace add mikecfisher/agent-debug-mode

Then install the plugin:

/plugin install debug-mode@mikecfisher-agent-debug-mode

Restart Claude Code to load the plugin. Restart Codex after installing skills there so the new skills are picked up.

Option 3: Claude plugin local development

git clone https://github.com/mikecfisher/agent-debug-mode.git
claude --plugin-dir ./agent-debug-mode

You can also load multiple plugins:

claude --plugin-dir ./agent-debug-mode --plugin-dir ./other-plugin

Usage

Workflow

1. Start debugging — Describe your bug:

   /debug-mode The checkout button isn't working
   

2. Reproduce — Follow Claude's reproduction steps to trigger the bug

3. Report result — Run one of:

   • /debug-reproduced — Bug still happening (Claude analyzes logs, iterates)
   • /debug-fixed — Bug is fixed (Claude cleans up instrumentation)

Autonomous Workflow

For bugs the agent can reproduce itself (web UI via Chrome DevTools MCP, failing tests, build errors, API issues, CLI scripts):

/debug-auto The checkout button doesn't submit the order

The agent handles the entire hypothesize → instrument → reproduce → analyze → fix → verify loop autonomously, up to 5 iterations. No manual reproduction steps needed.

Requirements: Web UI debugging requires Chrome DevTools MCP. CLI, test, build, and API bugs work with just Bash.

When to use which:

• /debug-auto — Agent can trigger the bug (clickable UI, runnable tests/builds/commands)
• /debug-mode — Bug requires physical device, specific user account, complex environment, or human judgment to reproduce

How It Works

1. /debug-mode — Claude generates hypotheses and instruments code

When you report a bug, Claude creates specific, testable theories:

ID	Hypothesis
A	items array is undefined when order.items isn't provided
B	Race condition: loadUser completes after renderProfile
C	API returns 200 but empty body on timeout

Then instruments your code with logging:

// Before
async function processOrder(orderId, items) {
  const validated = validateItems(items);
  return await saveOrder(orderId, validated);
}

// After (instrumented)
async function processOrder(orderId, items) {
  __debugLog("orders.ts:processOrder", "A", "Entry", { orderId, itemCount: items?.length });

  const validated = validateItems(items);
  __debugLog("orders.ts:processOrder", "A", "After validation", { validated: !!validated });

  return await saveOrder(orderId, validated);
}

2. You reproduce the bug

Follow Claude's reproduction steps. Logs capture exactly what happens at runtime.

3. /debug-reproduced — Claude analyzes and iterates

=== Debug Log Analysis ===
Total events: 12
Time range: 14:32:05.123 - 14:32:05.891

--- Hypothesis A (8 events) ---
Errors:
  [14:32:05.156] orders.ts:processOrder
    Cannot read property 'length' of undefined

--- Hypothesis B (4 events) ---
Errors: None

=== Summary ===
Hypothesis A has 1 error - likely root cause.

Claude implements a fix (keeping instrumentation), then asks you to reproduce again. This cycle continues until the bug is fixed.

4. /debug-fixed — Clean up

Claude removes all instrumentation and provides a summary of the root cause and fix.

Requirements

• Claude Code or Codex
• Node.js 18+ or Bun

Configuration

Variable	Default	Description
DEBUG_PORT	7777	Port for the log collector server

DEBUG_PORT=8080 claude --plugin-dir ./agent-debug-mode

For skill installs, DEBUG_PORT is read by the bundled helper scripts at runtime. No agent-specific environment variables are required.

How Logs Are Collected

Debug Mode runs a lightweight HTTP server on localhost that collects log entries. Logs are written to .debug/debug.log in your project directory.

• Browser code: Logs via fetch() to the collector
• Server code: Logs directly to the file system
• Logs are local: Nothing leaves your machine

Add .debug/ to your .gitignore to avoid committing debug logs.

License

MIT

Contributing

Issues and PRs welcome at github.com/mikecfisher/agent-debug-mode.