{
  "markdown": "# Python Remote Debug Skill\n\nA Claude Code plugin for debugging running Python processes using Python 3.14+ [remote debugging](https://docs.python.org/3/howto/remote_debugging.html) via `sys.remote_exec()`. This skill enables you to inject debugging scripts into live processes to get stack traces without stopping them.\n\n## Features\n\n- **Remote Process Inspection**: Inject Python scripts into running processes\n- **Thread Stack Traces**: Get stack traces from all threads in a process\n- **Gevent/Greenlet Support**: Special handling for gevent-based workers (like Celery with `-P gevent`)\n- **Zero Downtime Debugging**: Diagnose stuck processes without stopping them\n\n## Prerequisites\n\n- **Python 3.14+** (both debugger and target process)\n- **Elevated privileges** (sudo or equivalent) to attach to other processes. See [section below](#configuring-sudo-for-claude-code) for more detailed instructions on this.\n\n## Installation\n\n### As a Claude Code Plugin (Recommended)\n\n1. Add the marketplace:\n```bash\n/plugin marketplace add promptromp/python-remote-debug-skill\n```\n\n2. Install the plugin:\n```bash\n/plugin install python-remote-debug-skill\n```\n\n### Local Development\n\nClone and load directly:\n```bash\ngit clone https://github.com/promptromp/python-remote-debug-skill.git\nclaude --plugin-dir ./python-remote-debug-skill\n```\n\n### Standalone Skill\n\nExtract the `skills/debug-remote/` folder to `~/.claude/skills/`:\n```bash\ncp -r skills/debug-remote ~/.claude/skills/\n```\n\n## Usage\n\nOnce installed, Claude can use the skill automatically when you ask about debugging Python processes, or invoke it directly:\n\n```\n/python-remote-debug-skill:debug-remote\n```\n\n### Example Prompts\n\n- \"Debug the stuck Celery worker process\"\n- \"Get stack traces from the Python process with PID 12345\"\n- \"Help me figure out why my gevent worker is hanging\"\n\n## Helper Scripts\n\nThe `skills/debug-remote/scripts/` directory contains ready-to-use debug scripts that can jumpstart the debugging process for some common scenarios involving concurrency:\n\n- `debug_threads.py` - Get stack traces from all OS threads\n- `debug_gevent.py` - Get stack traces from all gevent greenlets\n\n## How It Works\n\nPython 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.\n\nKey characteristics:\n- Script executes in the target process's context\n- Output must be written to a file (stdout/stderr not visible)\n- Call returns immediately; execution happens asynchronously\n- If blocked in C code, script waits until Python resumes\n\n## Common Issues Detected\n\nThis technique can reveal:\n\n1. **Stuck in external library**: Process waiting in third-party code\n2. **ThreadPoolExecutor deadlock**: Thread pool conflicts with gevent\n3. **Missing timeouts**: HTTP clients without timeout parameters\n4. **Unenforced time limits**: gevent cooperative scheduling bypassing limits\n\n## Configuring sudo for Claude Code\n\nRemote 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:\n\n### Option 1: Full sudo Access (Simplest)\n\nGrant your user passwordless sudo for all commands:\n\n```bash\nsudo visudo\n```\n\nAdd this line (replace `yourusername` with your actual username):\n\n```\nyourusername ALL=(ALL) NOPASSWD: ALL\n```\n\n> **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.\n\n### Option 2: Passwordless sudo for Python Only (Recommended)\n\nA more secure approach—allow passwordless sudo only for the specific Python interpreter:\n\n```bash\nsudo visudo\n```\n\nAdd this line (adjust paths to match your Python 3.14 installation):\n\n```\nyourusername ALL=(ALL) NOPASSWD: /opt/homebrew/bin/python3.14, /usr/local/bin/python3.14, /usr/bin/python3.14\n```\n\nThis grants passwordless sudo only for the Python 3.14 interpreter, limiting exposure.\n\n### Option 3: Dedicated User with Limited sudo (Advanced)\n\nFor stricter isolation, create a dedicated user for Claude Code sessions.\n\n**On macOS:**\n\n```bash\nsudo dscl . -create /Users/claudecode\nsudo dscl . -create /Users/claudecode UserShell /bin/zsh\nsudo dscl . -create /Users/claudecode UniqueID 550\nsudo dscl . -create /Users/claudecode PrimaryGroupID 20\nsudo dscl . -create /Users/claudecode NFSHomeDirectory /Users/claudecode\nsudo mkdir -p /Users/claudecode\nsudo chown claudecode:staff /Users/claudecode\n```\n\n**On Linux:**\n\n```bash\nsudo useradd -m -s /bin/bash claudecode\n```\n\nThen add to `/etc/sudoers`:\n\n```\nclaudecode ALL=(ALL) NOPASSWD: /opt/homebrew/bin/python3.14, /usr/local/bin/python3.14, /usr/bin/python3.14\n```\n\nRun Claude Code as this user:\n\n```bash\nsudo -u claudecode claude\n```\n\n### Linux-Specific: Relaxing ptrace Restrictions\n\nOn Linux systems with Yama enabled, you can alternatively relax ptrace restrictions system-wide (until reboot):\n\n```bash\necho 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope\n```\n\nThis allows any process to ptrace any other process owned by the same user, which may reduce the need for sudo in some scenarios.\n\n### Docker and Containers\n\nIf running inside a container, you must explicitly grant the `SYS_PTRACE` capability:\n\n```bash\ndocker run --cap-add=SYS_PTRACE ...\n```\n\nNote that even with this capability, you may still need root inside the container.\n\n### Security Considerations\n\n- **Principle of least privilege**: Option 2 is preferred for most users—it balances convenience with security.\n- **Audit trail**: sudo usage is logged (`/var/log/auth.log` on Linux, `/var/log/system.log` on macOS).\n- **Process targeting**: The debug scripts only write to `/tmp/` and cannot modify the target process's state—they only read stack frames.\n\n## Further Reading\n\nFor a detailed write-up on the techniques used in this skill, including a real-world example and the motivation behind combining Python 3.14's remote debugging with LLM assistance, see:\n\n**[Debugging Stuck Processes with Python 3.14 and LLM Assistance](https://adamhadani.github.io/debugging/python/llm/2026/01/23/debugging-stuck-processes-python314-llm.html)**\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n## Contributing\n\nContributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.\n",
  "bytes": 6686,
  "sha": "13df63d45c578678a65f4d22a018a88ec424b2b28fbd0408f848d7cce093a1a9",
  "repo_slug": "promptromp/python-remote-debug-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_promptromp_python_remote_debug_skill_pyt_2d3181bc/readme"
}