# Python Debugpy

Debug Python: pdb REPL + debugpy remote (DAP).

- Repository: https://github.com/mateaix/mateclaw (1176 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mateaix/mateclaw --skill python-debugpy -g -a claude-code -y`
Codex: `npx skills add mateaix/mateclaw --skill python-debugpy -g -a codex -y`
Cursor: `npx skills add mateaix/mateclaw --skill python-debugpy -g -a cursor -y`
Gemini CLI: `npx skills add mateaix/mateclaw --skill python-debugpy -g -a gemini-cli -y`

## Description

Debug Python: pdb REPL + debugpy remote (DAP).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Python Debugger (pdb + debugpy)

## Overview

Three tools, picked by situation:

| Tool | When |
|---|---|
| **`breakpoint()` + pdb** | Local, interactive, simplest. Add `breakpoint()` in the source, run normally, get a REPL at that line. |
| **`python -m pdb`** | Launch an existing script under pdb with no source edits. Useful for quick poking. |
| **`debugpy`** | Remote / headless / "attach to already-running process." Talks DAP, scriptable from terminal, works for long-lived processes (gateway, daemon, PTY children). |

**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 (the agent gateway, tui_gateway) misbehaves and you can't restart it
- Post-mortem: an exception fired in prod-ish code and you want to inspect locals at the crash site
- A subprocess / child (Python `_SlashWorker`, PTY bridge worker) 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)`):

The rest: https://github.com/mateaix/mateclaw/blob/HEAD/mateclaw-server/src/main/resources/skills/python-debugpy/SKILL.md