Vibe Debug

A debugger CLI and MCP server for coding agents.

vibe-debug gives Codex, Claude Code, Cursor-style agents, and other MCP clients real debugger tools: launch, attach, set breakpoints, continue, step into/out/over, inspect stack frames, read locals, expand variables, evaluate expressions, and stop sessions.

The goal is simple: when an agent is fixing a bug, it should be able to use a debugger the same way a human engineer would.

coding agent
  -> CLI command or MCP tool call
  -> vibe-debug
  -> Debug Adapter Protocol
  -> language debugger backend
  -> your app

Claude Code Skill Install

Default path: install a lightweight project skill. This keeps debugger tools out of Claude's global MCP context and lets Claude discover the CLI when a Python bug needs runtime state.

npx -y github:illscience/vibe-debug doctor
npx -y github:illscience/vibe-debug init-cli-skill --target claude

That writes .claude/skills/vibe-debug/SKILL.md: a short skill whose frontmatter explicitly triggers on reproducible Python bugs, failing Python tests/scripts, wrong output, exceptions, and logic errors where live runtime state would help. The skill body is CLI documentation for debug-python.

Codex Skill Install

npx -y github:illscience/vibe-debug doctor
npx -y github:illscience/vibe-debug init-cli-skill --target codex

That writes .codex/skills/vibe-debug/SKILL.md.

Optional MCP Install

MCP is still supported if you want debugger tools exposed directly to the agent.

Claude Code:

claude mcp add -s user vibe-debug -- npx -y github:illscience/vibe-debug

Codex:

codex mcp add vibe_debug -- npx -y github:illscience/vibe-debug

Codex's MCP config table names are safest with underscores, so the Codex config entry is vibe_debug even though the project and MCP server identify as vibe-debug.

Other MCP Clients

Use this stdio server config:

{
  "mcpServers": {
    "vibe-debug": {
      "command": "npx",
      "args": ["-y", "github:illscience/vibe-debug"],
      "env": {}
    }
  }
}

MCP Health Check

The MCP server uses a small Python/debugpy cache behind the npx wrapper. Warm and verify it with:

npx -y github:illscience/vibe-debug doctor

Expected output:

vibe-debug 0.2.2
Python: ...
debugpy import: ok
MCP initialize: ok

For the full machine-readable report, run npx -y github:illscience/vibe-debug doctor --json.

Disable MCP

MCP tools are visible to the agent while the server is enabled. If you only want debugger tools for a specific project or debugging session, remove the MCP entry when you are done:

claude mcp remove vibe-debug -s user
codex mcp remove vibe_debug

Use The CLI Directly

You can also run the debugger as a normal CLI from any coding agent shell. This avoids adding persistent MCP tools when you only need debugger state for a single bug:

npx -y github:illscience/vibe-debug debug-python ./buggy_invoice.py --break ./buggy_invoice.py:13 --eval "subtotal * (1 - rate)"

Human output is concise:

Stopped: buggy_invoice.py:13 in invoice_total
Reason: breakpoint
Locals:
  customer_tier = 'gold'
  rate = 0.15
  subtotal = 120.0
  total = 119.85
Evaluations:
  subtotal * (1 - rate) -> 102.0

Use --json when you want machine-readable output for an agent or script:

npx -y github:illscience/vibe-debug debug-python ./buggy_invoice.py --break ./buggy_invoice.py:13 --eval "subtotal * (1 - rate)" --json

Status

This is an alpha release. The first debugger backend is Python via debugpy; the MCP server is designed to grow to TypeScript/Node and other language runtimes.

The npm package name in this repository is @illscience/vibe-debug. Until it is published to npm, the install commands use npx -y github:illscience/vibe-debug. After publishing, that can become:

npx -y @illscience/vibe-debug

Optional Clean-Room Test

This proves the default skill/CLI workflow works from a normal bug-fixing prompt, without installing the MCP and without explicitly telling the agent which debugger command to call.

Claude Code

Paste this block:

npx -y github:illscience/vibe-debug doctor

claude mcp remove vibe-debug -s local 2>/dev/null || true
claude mcp remove vibe-debug -s user 2>/dev/null || true

rm -rf /tmp/vibe-debug-claude-verify
mkdir /tmp/vibe-debug-claude-verify
cd /tmp/vibe-debug-claude-verify
npx -y github:illscience/vibe-debug demo-project --target claude .

claude -p --output-format stream-json --verbose "There is a bug in buggy_invoice.py. Figure out what is wrong and propose the fix. Do not edit files." | npx -y github:illscience/vibe-debug claude-progress

The demo-project command creates:

• buggy_invoice.py: a tiny Python program with a real arithmetic bug.
• CLAUDE.md: Claude Code project memory that says to prefer live runtime debugging for reproducible bugs.
• .claude/skills/vibe-debug/SKILL.md: the local skill that teaches Claude the CLI workflow.

Claude Code loads project instructions from ./CLAUDE.md (Anthropic docs). vibe-debug can create that file for you in a test project, as shown above.

What you want to see:

• Claude uses the vibe-debug skill and runs npx -y github:illscience/vibe-debug debug-python ....
• The progress formatter shows Tool: Bash (vibe-debug debug-python).
• The progress formatter shows a stopped location near buggy_invoice.py:13.
• Claude reports runtime values such as subtotal = 120.0, customer_tier = 'gold', and rate = 0.15.
• Claude explains that the program subtracts 0.15 directly instead of subtracting 120.0 * 0.15.
• Claude proposes total = subtotal * (1 - rate) or total = subtotal - (subtotal * rate).

Codex

npx -y github:illscience/vibe-debug doctor

codex mcp remove vibe_debug 2>/dev/null || true

rm -rf /tmp/vibe-debug-codex
mkdir /tmp/vibe-debug-codex
cd /tmp/vibe-debug-codex
npx -y github:illscience/vibe-debug demo-project --target codex .
codex exec "There is a bug in buggy_invoice.py. Figure out what is wrong and propose the fix. Do not edit files."

The key proof is the transcript: the agent should use vibe-debug from a normal debugging request and cite observed runtime state in its answer.

What The Skill Teaches

The project skill teaches the agent to run:

npx -y github:illscience/vibe-debug debug-python <script.py> --break <file.py>:<line> --json

The CLI launches the target script under debugpy, stops at the requested breakpoint, and returns the stopped location, locals, and optional expression evaluations.

Optional MCP Tools

The MCP server exposes agent-friendly workflow tools and lower-level debugger primitives.

Workflow tools:

• debug_guidance: returns instructions that tell agents when to use the debugger.
• debug_python_repro: best first tool for a reproducible Python bug. It launches a Python script under debugpy, sets breakpoints, continues to the first stop, and returns stack plus top-frame locals.

Debugger primitives:

• debug_launch: launch a Python script under debugpy.
• debug_attach: attach to an existing debugpy listener.
• debug_set_breakpoints: set file/line breakpoints.
• debug_continue: continue until breakpoint, exception, process exit, or timeout.
• debug_step: step over, into, or out.
• debug_stack: inspect stack frames.
• debug_scopes: inspect scope handles for a frame.
• debug_variables: expand locals, globals, objects, lists, or dicts.
• debug_evaluate: evaluate an expression in a paused frame.
• debug_stop: disconnect and clean up a session.

Scripted Runtime Proof

The repository also includes a deterministic proof script for CI and development:

python tools/runtime_proof.py

If using the local venv:

.venv/bin/python tools/runtime_proof.py

The proof talks to the MCP server over stdio, launches examples/buggy_discount.py under debugpy, sets a breakpoint, continues to it, steps into and out of functions, inspects local variables, evaluates expressions in a paused frame, tests attach mode, and cleans up the session.

Expected output:

{
  "ok": true,
  "proved": [
    "MCP initialize/tools/list",
    "debug_guidance",
    "debug_python_repro",
    "debug_launch",
    "debug_attach",
    "debug_set_breakpoints",
    "debug_continue to breakpoint",
    "debug_step into",
    "debug_scopes/debug_variables locals",
    "debug_step out",
    "debug_step over",
    "debug_evaluate",
    "debug_evaluate default top frame",
    "debug_continue to exit"
  ],
  "bugEvidence": {
    "runtimeBuggyExpression": "119.85",
    "runtimeExpectedExpression": "102.0"
  }
}

Example: What A Successful Agent Run Looks Like

Given this bug:

def apply_discount(price, loyalty_level):
    rate = lookup_rate(loyalty_level)
    discounted = price - rate  # BUG: should subtract price * rate.
    return round(discounted, 2)

An agent can run vibe-debug debug-python, stop at the breakpoint, inspect locals, and observe:

price = 120.0
loyalty_level = 'gold'
rate = 0.15
discounted = 119.85
correct_total = 102.0

The resulting explanation is based on runtime state:

The program subtracts the rate value itself, 0.15, from 120.0.
For a 15% discount it should subtract price * rate, which is 18.0.
The correct total is 102.0, not 119.85.

How To Make Agents Use It Naturally

The project skill makes the CLI discoverable, but the agent still needs a workflow preference that says runtime bugs should be investigated with live runtime state when possible.

For Claude Code, use CLAUDE.md. Anthropic documents ./CLAUDE.md as project memory that Claude Code loads automatically.

For Codex, use AGENTS.md.

Create the right file in a target project:

npx -y github:illscience/vibe-debug init-cli-skill --target claude
npx -y github:illscience/vibe-debug init-cli-skill --target codex
npx -y github:illscience/vibe-debug init-cli-skill --target both
npx -y github:illscience/vibe-debug init-agent-files --target claude
npx -y github:illscience/vibe-debug init-agent-files --target codex
npx -y github:illscience/vibe-debug init-agent-files --target both

Or print the guidance:

npx -y github:illscience/vibe-debug agent-instructions --target claude
npx -y github:illscience/vibe-debug agent-instructions --target codex

The key instruction:

When a Python bug has a reproducible script, test, command, or request, prefer observing live runtime state before proposing a fix.

The skill frontmatter is intentionally explicit so agents can load it when a Python bug has observable runtime state.

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python tools/runtime_proof.py

Build a wheel:

.venv/bin/python -m pip wheel . -w /tmp/vibe-debug-wheel

Safety

debug_evaluate can execute code inside the target process. Treat it like running code in the debuggee. The server defaults to localhost debug adapter connections and cleans up launched sessions when the MCP server exits.

Roadmap

• debug_pytest_failure: run a failing pytest test under the debugger automatically.
• Breakpoints by function name, symbol, marker comment, or exception type.
• Richer first-stop summaries with surrounding source and suggested next debugger actions.
• Agent-optimized CLI commands, with MCP as a thin wrapper for clients that prefer tools over shell commands.
• Node.js / Next.js support through the Node inspector or Chrome DevTools Protocol.

License

MIT