[FEATURE] Interactive "Debug Mode" with Runtime Log Instrumentation

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When dealing with complex bugs—specifically race conditions, state management issues, or problems that are difficult to reproduce via static analysis alone—Claude Code currently relies heavily on the user manually providing context (pasting error logs, describing behavior) or running existing tests.

While Claude Code can write tests to reproduce issues, there are scenarios (especially in UI development, complex backend services, or specific environment configurations) where writing a test case is difficult or time-consuming. Currently, if I want to debug a runtime issue, I have to:

1. Manually ask Claude to add print/log statements.
2. Manually run the app/script.
3. Copy/paste the terminal output back into Claude Code.
4. Ask Claude to analyze it.
5. Ask Claude to remove the logs afterwards.

This manual "human-in-the-loop" data transfer is slow and error-prone, often leading to "shotgun debugging" where the model guesses the solution without concrete runtime evidence.

Proposed Solution

I propose adding a dedicated Debug Mode (accessible via /debug or a built-in specialized subagent) that automates the "hypothesis -> instrumentation -> verification" loop.

Ideal User Experience:

1. Initiation: User types claude /debug "The payment form submits twice when clicking fast."
2. Hypothesis & Instrumentation: Claude analyzes the code, forms hypotheses, and automatically injects temporary logging/telemetry into the relevant files (using Edit) to track variable states and execution flow.
3. Interactive Reproduction: Claude spins up a background listener (using Bash or BashOutput to tail logs) and prompts the user: "I've added logging to payment.ts. Please reproduce the bug in your application now. Press Enter when done."
4. Analysis: Once the user reproduces the issue, Claude analyzes the captured runtime logs to validate its hypothesis.
5. Fix & Verify: Claude proposes a fix based on the concrete data.
6. Cleanup: Upon confirmation, Claude automatically reverts the instrumentation (removes the temporary logs), leaving the codebase clean.

Alternative Solutions

• Current Workflow: Manually instructing Claude: "Add console logs to function X, I will run it and paste the output." This creates friction and context switching.
• Test Generation: Asking Claude to "write a test case to reproduce this." This is the ideal path for logic bugs, but fails for issues dependent on user interaction, specific timing, or external services that are hard to mock quickly.
• Static Analysis: Relying on the Explore subagent. This finds syntax or logic errors visible in text but fails to catch runtime state issues (e.g., a variable being null at a specific moment in time).

Priority

High - Significant impact on productivity

Feature Category

Other

Use Case Example

Scenario: Debugging a race condition in a Node.js API endpoint.

1. Developer: Runs claude /debug "The /api/process-order endpoint sometimes returns a 500 error regarding a duplicate key, but I have unique constraints."
2. Claude: "I need to see the order of execution between the database check and the insert. I am adding timestamped logs to controllers/order.js and services/db.js."
3. Claude: Edits files to add console.log('[DEBUG_TRACE]', ...).
4. Claude: "I am tailing the server logs. Please trigger the request that causes the 500 error."
5. Developer: Triggers the API call via Postman/Frontend.
6. Claude (via BashOutput): Detects the log output. "I see that two requests initiated db.insert within 2ms of each other before the first transaction committed. This is a race condition."
7. Claude: "I will implement a database transaction with a lock to fix this."
8. Developer: Accepts the fix.
9. Claude: Automatically removes the console.log statements added in step 2.

Additional Context

Similar Features:
This request is heavily inspired by Cursor's "Debug Mode", which introduces an agent loop specifically for runtime logging. It generates hypotheses, instruments code, waits for user reproduction, and verifies fixes.

Technical Feasibility in Claude Code:
Claude Code already possesses the necessary primitives to build this:

• Edit Tool: To insert and remove logging statements.
• Bash & BashOutput Tools: To start the application (if needed) or tail log files/streams to capture the output of the instrumentation.
• Subagents: This fits perfectly as a specialized debugger subagent (as referenced in the docs) but with a formalized workflow for user-interaction (waiting for reproduction).
• AskUserQuestion Tool: To coordinate the "Please reproduce the bug now" step.

This feature would significantly bridge the gap between "coding assistant" and "autonomous debugger."