version: "1.0.0" name: python-debugpy description: "Debug Python: pdb REPL + debugpy remote (DAP)." allowed-tools:

• bash
• read_file

enabled: true related-skills: [systematic-debugging, node-inspect-debugger] license: MIT author: Adapted from hermes-agent (Nous Research, MIT)

Python Debugger (pdb + debugpy)

Overview

Three tools, picked by situation:

Start with `breakpoint()`. It's the cheapest thing that works.

When to Use

• A test fails and the traceback doesn't reveal why a value is wrong
• You need to step through a function and watch a collection mutate
• A long-running process misbehaves and you can't restart it
• Post-mortem: an exception fired and you want to inspect locals at crash site
• A subprocess is the actual bug site

Don't use for: things print() / logging.debug solve in under a minute, or things pytest -vv --tb=long --showlocals already reveals.

pdb Quick Reference

Inside any pdb prompt ((Pdb)):

Using breakpoint()

def process(data):
    result = transform(data)
    breakpoint()  # Execution pauses here, pdb REPL opens
    return result

Run normally:

python script.py
# Pauses at breakpoint(), (Pdb) prompt appears

Using python -m pdb (no source edits)

python -m pdb script.py
# Starts paused at first line

Post-mortem debugging

Drop into pdb at the exact exception site:

import pdb, traceback
try:
    main()
except Exception:
    traceback.print_exc()
    pdb.post_mortem()

Or:

python -m pdb -c continue script.py
# Runs until exception, then drops to pdb at the crash

debugpy (remote attach)

For long-running processes or headless debugging:

# Install
pip install debugpy
 
# Option 1: Launch with debugpy
python -m debugpy --listen 5678 --wait-for-client script.py
 
# Option 2: Inject into running code
import debugpy
debugpy.listen(5678)
print("Waiting for debugger on port 5678...")
debugpy.wait_for_client()

Attach from another terminal (DAP client):

# Using debugpy's CLI to set breakpoints + continue
python -m debugpy --connect localhost:5678 --set-breakpoint script.py:42

Or use any DAP-compatible editor (VS Code, Neovim) to attach to port 5678.

Common Debugging Patterns

Watch a variable change

# In pdb
(Pdb) display my_list
# Each step, pdb re-evaluates and shows the value if changed

Conditional breakpoint

# In source
breakpoint() if condition else None
# Or in pdb
(Pdb) b 42, x > 100  # Break at line 42 only when x > 100

Inspect a running subprocess

import debugpy
# In the subprocess code:
debugpy.listen(5679)
debugpy.wait_for_client()
# Parent can attach to port 5679

Pitfalls

• breakpoint() in production: remove before commit. Use breakpoint() only

for local debugging.

• pdb + multiprocessing: child processes don't inherit the pdb prompt.

Use debugpy for multi-process debugging.

• pdb + asyncio: pdb works but async stack traces can be confusing. Use

w (where) to see the full async call stack.

• Windows + pdb: some pdb features work differently on Windows. `python -m

pdb is more reliable than breakpoint()` in some Windows terminals.

• debugpy port conflicts: default port 5678 may be taken. Use

--listen 5679.