Python Remote Debug Skill
A Claude Code plugin for debugging running Python processes using Python 3.14+ remote debugging via sys.remote_exec(). This skill enables you to inject debugging scripts into live processes to get stack traces without stopping them.
Features
- Remote Process Inspection: Inject Python scripts into running processes
- Thread Stack Traces: Get stack traces from all threads in a process
- Gevent/Greenlet Support: Special handling for gevent-based workers (like Celery with
-P gevent)
- Zero Downtime Debugging: Diagnose stuck processes without stopping them
Prerequisites
- Python 3.14+ (both debugger and target process)
- Elevated privileges (sudo or equivalent) to attach to other processes. See section below for more detailed instructions on this.
Installation
As a Claude Code Plugin (Recommended)
- Add the marketplace:
/plugin marketplace add promptromp/python-remote-debug-skill
- Install the plugin:
/plugin install python-remote-debug-skill
Local Development
Clone and load directly:
git clone https://github.com/promptromp/python-remote-debug-skill.git
claude --plugin-dir ./python-remote-debug-skill
Standalone Skill
Extract the skills/debug-remote/ folder to ~/.claude/skills/:
cp -r skills/debug-remote ~/.claude/skills/
Usage
Once installed, Claude can use the skill automatically when you ask about debugging Python processes, or invoke it directly:
/python-remote-debug-skill:debug-remote
Example Prompts
- "Debug the stuck Celery worker process"
- "Get stack traces from the Python process with PID 12345"
- "Help me figure out why my gevent worker is hanging"
Helper Scripts
The skills/debug-remote/scripts/ directory contains ready-to-use debug scripts that can jumpstart the debugging process for some common scenarios involving concurrency:
debug_threads.py - Get stack traces from all OS threads
debug_gevent.py - Get stack traces from all gevent greenlets
How It Works
Python 3.14 introduced sys.remote_exec() which allows injecting Python scripts into running processes. The script executes asynchronously at the next "safe point" in the interpreter.
Key characteristics:
- Script executes in the target process's context
- Output must be written to a file (stdout/stderr not visible)
- Call returns immediately; execution happens asynchronously
- If blocked in C code, script waits until Python resumes
Common Issues Detected
This technique can reveal:
- Stuck in external library: Process waiting in third-party code
- ThreadPoolExecutor deadlock: Thread pool conflicts with gevent
- Missing timeouts: HTTP clients without timeout parameters
- Unenforced time limits: gevent cooperative scheduling bypassing limits
Configuring sudo for Claude Code
Remote debugging requires elevated privileges to attach to other processes on most Unix-like systems. On macOS, this is needed for the com.apple.system-task-ports entitlement. On Linux, the ptrace system call is restricted by the Yama security module (enabled by default on Ubuntu and many other distributions). When Claude Code runs sys.remote_exec(), it needs sudo access. Here are several approaches, from simplest to most secure:
Option 1: Full sudo Access (Simplest)
Grant your user passwordless sudo for all commands:
sudo visudo
Add this line (replace yourusername with your actual username):
yourusername ALL=(ALL) NOPASSWD: ALL
Warning: This grants your user root-equivalent access without a password for any command. Only use this on personal development machines where convenience outweighs security concerns. Not recommended for shared or production systems.
Option 2: Passwordless sudo for Python Only (Recommended)
A more secure approach—allow passwordless sudo only for the specific Python interpreter:
sudo visudo
Add this line (adjust paths to match your Python 3.14 installation):
yourusername ALL=(ALL) NOPASSWD: /opt/homebrew/bin/python3.14, /usr/local/bin/python3.14, /usr/bin/python3.14
This grants passwordless sudo only for the Python 3.14 interpreter, limiting exposure.
Option 3: Dedicated User with Limited sudo (Advanced)
For stricter isolation, create a dedicated user for Claude Code sessions.
On macOS:
sudo dscl . -create /Users/claudecode
sudo dscl . -create /Users/claudecode UserShell /bin/zsh
sudo dscl . -create /Users/claudecode UniqueID 550
sudo dscl . -create /Users/claudecode PrimaryGroupID 20
sudo dscl . -create /Users/claudecode NFSHomeDirectory /Users/claudecode
sudo mkdir -p /Users/claudecode
sudo chown claudecode:staff /Users/claudecode
On Linux:
sudo useradd -m -s /bin/bash claudecode
Then add to /etc/sudoers: