A Claude Code skill that enables interactive Python debugging (pdb) sessions through tmux.

Claude Code cannot attach to interactive TTY/stdin, which makes using interactive debuggers like pdb impossible through normal means.

This skill uses tmux as an intermediary:

• 🖥️ pdb runs in a tmux pane with a real TTY for interactive input
• 🤖 Claude interacts via tmux commands: capture-pane to read output, send-keys to send commands

This gives you full pdb debugging capabilities within Claude Code.

• 🟢 tmux installed and available in PATH
• 🐍 Python 3.8+
• 📦 (Optional) uv for package management

1. Clone this repository:

   git clone https://github.com/maspectra/python-debug-skill.git

2. Copy the skill to your project:

   cp -r python-debug-skill/.claude/skills/pdb-tmux YOUR_PROJECT/.claude/skills/

   Or symlink for development:

   ln -s /path/to/python-debug-skill/.claude/skills/pdb-tmux YOUR_PROJECT/.claude/skills/pdb-tmux

Once installed, simply ask Claude Code to debug your Python file:

Use the pdb-tmux skill to debug app.py

Debug my_script.py using pdb-tmux and help me find the bug

Use pdb-tmux to step through the calculate_total function in utils.py

Claude will automatically start a pdb session, set breakpoints, step through code, and inspect variables to help you debug.

You can also invoke the skill directly:

/pdb-tmux start -- python -m pdb your_script.py
/pdb-tmux start -- uv run python -m pdb your_script.py   # with uv

.claude/skills/pdb-tmux/
├── SKILL.md          # Skill specification (loaded by Claude Code)
└── scripts/
    ├── start.sh      # Initialize pdb session in tmux
    ├── capture.sh    # Read current pane output
    └── send.sh       # Send pdb command and capture response

Workflow pattern: Capture → Send → Capture

1. 📸 Capture current state (optional, for context)
2. 📤 Send one pdb command
3. 📸 Capture and display new output

1. 🎬 Start: Creates a tmux session named dbg and launches pdb inside it
2. 📸 Capture: Uses tmux capture-pane to read the terminal output
3. 📤 Send: Uses tmux send-keys to type commands into the pdb session

The scripts handle proper shell escaping for commands with spaces and special characters.

Specify a different tmux session:

/pdb-tmux start mysession -- python -m pdb script.py
/pdb-tmux send mysession "n"

/pdb-tmux send "b my_function, x > 10"
/pdb-tmux send "b script.py:42, len(items) == 0"

/pdb-tmux start -- python -m pdb -c continue script.py

MIT License - see LICENSE file for details.

Made with ❤️ by Maspectra Dev Team