Debug Mode for AI Agents

A debugging toolkit that helps AI agents systematically investigate and fix bugs using runtime log instrumentation, inspired by Cursor's Debug Mode.

How It Works

1. Start the debug server from your project directory
2. Add simple fetch() calls to instrument suspicious code
3. Reproduce the bug → logs are captured
4. Analyze logs to find root cause
5. Fix and verify

Quick Start

1. Start the Debug Server

# Navigate to YOUR project (logs will be saved here)
cd /path/to/your-project

# Start the debug server
python /path/to/debugging_mcp/src/server/debug_server.py

Logs are saved to ./logs/ in your current directory.

2. Add Debug Logging (No Library Required)

Just use fetch() directly in your code:

JavaScript/TypeScript:

await fetch('http://localhost:9876/log', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    timestamp: new Date().toISOString(),
    level: 'debug',
    message: 'Checking user permissions',
    hypothesis: 'H1',  // Tag with hypothesis ID
    context: { userId: 123, role: user.role }
  })
});

Python:

import requests
requests.post('http://localhost:9876/log', json={
    'level': 'debug',
    'message': 'Checking user permissions',
    'hypothesis': 'H1',
    'context': {'user_id': 123, 'role': user.role}
}, timeout=1)

3. Reproduce & Analyze

# View logs
cat ./logs/debug_session_*.jsonl

# Or use the analysis tools
python /path/to/debugging_mcp/src/cli.py analyze

The Debug Mode Process

1. Hypothesize - Generate 3-5 hypotheses (H1, H2, H3...) about root cause
2. Instrument - Add debug logs tagged with hypothesis IDs
3. Reproduce - User triggers the bug
4. Analyze - Review logs to validate/invalidate hypotheses
5. Fix - Make minimal, targeted fix
6. Verify - Confirm bug is resolved
7. Cleanup - Remove debug instrumentation

Server Endpoints

Endpoint	Method	Description
/log	POST	Submit a log entry
/status	GET	Server status
/logs	GET	Get all logs
/clear	POST	Clear all logs

Log Format

Each log entry (JSON):

{
  "timestamp": "2024-12-13T10:30:00.000Z",
  "level": "debug",
  "message": "User authentication check",
  "hypothesis": "H1",
  "context": { "user_id": 123 }
}

Project Structure

debugging_mcp/
├── src/
│   ├── server/debug_server.py   # HTTP server for receiving logs
│   ├── analysis/                # Log parsing tools
│   └── cli.py                   # CLI helper
└── .agent/workflows/
    └── debug-mode.md            # AI agent workflow guide

Auto-Start in VSCode-Based Editors

To automatically start the debug server when opening your project in VSCode, Cursor, or Antigravity:

Option 1: Per-Project Task (Recommended)

Add to your project's .vscode/tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Start Debug Server",
            "type": "shell",
            "command": "python",
            "args": ["/path/to/debugging_mcp/src/server/debug_server.py"],
            "isBackground": true,
            "problemMatcher": [],
            "presentation": {
                "reveal": "silent",
                "panel": "dedicated"
            },
            "runOptions": {
                "runOn": "folderOpen"
            }
        }
    ]
}

Important: Update the path to where you cloned debugging_mcp.

Option 2: Shell Alias

Add to your ~/.zshrc or ~/.bashrc:

alias debug-server="python /path/to/debugging_mcp/src/server/debug_server.py"

Then just run debug-server in your project directory.

License

MIT