interactive-debugging - SKILL.md Agent Skill

name: interactive-debugging description: Patterns for controlling interactive debuggers (pdb, ipdb, gdb, lldb, node debug) via terminalcp

Interactive Debugging with terminalcp

This skill provides comprehensive patterns for automating interactive debugger sessions using terminalcp MCP. It enables AI agents to spawn, control, and extract information from debuggers in real-time.

Overview

terminalcp enables:

Real-time debugger control via PTY
Breakpoint management and inspection
Step-by-step execution with state capture
Variable inspection and expression evaluation
Multi-debugger session management

The MCP server runs via npx @mariozechner/terminalcp@latest --mcp and provides full terminal emulation for debugger interaction.

Python Debugging (pdb/ipdb)

Starting a Debug Session

{
  "action": "start",
  "command": "python -m pdb script.py",
  "name": "python-debug"
}

Or with ipdb for enhanced debugging:

{
  "action": "start",
  "command": "python -m ipdb script.py",
  "name": "python-debug"
}

Setting Breakpoints

{
  "action": "stdin",
  "id": "python-debug",
  "data": "b script.py:42\r"
}

Set conditional breakpoint:

{
  "action": "stdin",
  "id": "python-debug",
  "data": "b script.py:42, x > 10\r"
}

Set breakpoint in function:

{
  "action": "stdin",
  "id": "python-debug",
  "data": "b my_function\r"
}

Execution Control

// Continue execution
{
  "action": "stdin",
  "id": "python-debug",
  "data": "c\r"
}

// Step into function
{
  "action": "stdin",
  "id": "python-debug",
  "data": "s\r"
}

// Step over (next line)
{
  "action": "stdin",
  "id": "python-debug",
  "data": "n\r"
}

// Return from current function
{
  "action": "stdin",
  "id": "python-debug",
  "data": "r\r"
}

// Continue until next breakpoint or return
{
  "action": "stdin",
  "id": "python-debug",
  "data": "unt 50\r"
}

Variable Inspection

// Print variable value
{
  "action": "stdin",
  "id": "python-debug",
  "data": "p variable_name\r"
}

// Pretty print
{
  "action": "stdin",
  "id": "python-debug",
  "data": "pp complex_object\r"
}

// List all local variables
{
  "action": "stdin",
  "id": "python-debug",
  "data": "locals()\r"
}

// Evaluate expression
{
  "action": "stdin",
  "id": "python-debug",
  "data": "p len(my_list) + 5\r"
}

Stack Frame Navigation

// Show stack trace
{
  "action": "stdin",
  "id": "python-debug",
  "data": "w\r"
}

// Move up one frame
{
  "action": "stdin",
  "id": "python-debug",
  "data": "u\r"
}

// Move down one frame
{
  "action": "stdin",
  "id": "python-debug",
  "data": "d\r"
}

// List source code at current location
{
  "action": "stdin",
  "id": "python-debug",
  "data": "l\r"
}

Capturing Debugger Output

{
  "action": "stdout",
  "id": "python-debug"
}

This returns the current terminal state including all debugger output, variable values, and stack traces.

GDB/LLDB Debugging (C/C++)

Starting GDB Session

{
  "action": "start",
  "command": "gdb ./myprogram",
  "name": "gdb-debug"
}

Starting LLDB Session

{
  "action": "start",
  "command": "lldb ./myprogram",
  "name": "lldb-debug"
}

GDB Breakpoint Management

// Set breakpoint at line
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "break main.c:42\r"
}

// Set breakpoint at function
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "break my_function\r"
}

// Conditional breakpoint
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "break main.c:42 if x > 10\r"
}

// List all breakpoints
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "info breakpoints\r"
}

// Delete breakpoint
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "delete 1\r"
}

LLDB Breakpoint Management

// Set breakpoint at line
{
  "action": "stdin",
  "id": "lldb-debug",
  "data": "breakpoint set --file main.c --line 42\r"
}

// Set breakpoint at function
{
  "action": "stdin",
  "id": "lldb-debug",
  "data": "breakpoint set --name my_function\r"
}

// List breakpoints
{
  "action": "stdin",
  "id": "lldb-debug",
  "data": "breakpoint list\r"
}

GDB Execution Control

// Start program
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "run\r"
}

// Start with arguments
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "run arg1 arg2\r"
}

// Continue
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "continue\r"
}

// Step into
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "step\r"
}

// Step over
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "next\r"
}

// Finish current function
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "finish\r"
}

GDB Variable Inspection

// Print variable
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "print variable_name\r"
}

// Print with format (hex)
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "print/x pointer\r"
}

// Display variable (auto-display on each stop)
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "display my_var\r"
}

// Show all local variables
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "info locals\r"
}

// Examine memory
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "x/10x $rsp\r"
}

Stack and Backtrace

// Show backtrace
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "backtrace\r"
}

// Show full backtrace with locals
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "backtrace full\r"
}

// Select frame
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "frame 2\r"
}

// Move up frame
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "up\r"
}

// Move down frame
{
  "action": "stdin",
  "id": "gdb-debug",
  "data": "down\r"
}

Node.js Debugging

Starting Node Debug Session

{
  "action": "start",
  "command": "node inspect script.js",
  "name": "node-debug"
}

Node Debugger Commands

// Continue execution
{
  "action": "stdin",
  "id": "node-debug",
  "data": "c\r"
}

// Step over
{
  "action": "stdin",
  "id": "node-debug",
  "data": "n\r"
}

// Step into
{
  "action": "stdin",
  "id": "node-debug",
  "data": "s\r"
}

// Step out
{
  "action": "stdin",
  "id": "node-debug",
  "data": "o\r"
}

// Set breakpoint at current line
{
  "action": "stdin",
  "id": "node-debug",
  "data": "sb()\r"
}

// Set breakpoint at line
{
  "action": "stdin",
  "id": "node-debug",
  "data": "sb('script.js', 42)\r"
}

// List breakpoints
{
  "action": "stdin",
  "id": "node-debug",
  "data": "breakpoints\r"
}

// Clear breakpoint
{
  "action": "stdin",
  "id": "node-debug",
  "data": "cb('script.js', 42)\r"
}

Node Variable Inspection

// Evaluate expression
{
  "action": "stdin",
  "id": "node-debug",
  "data": "exec('myVariable')\r"
}

// Enter REPL mode
{
  "action": "stdin",
  "id": "node-debug",
  "data": "repl\r"
}

// In REPL, inspect objects
{
  "action": "stdin",
  "id": "node-debug",
  "data": "myObject.property\r"
}

// Exit REPL
{
  "action": "stdin",
  "id": "node-debug",
  "data": "\u0003"
}

Note: \u0003 is Ctrl+C to exit REPL mode.

Advanced Patterns

Automated Bug Investigation Workflow

// 1. Start debugger
{
  "action": "start",
  "command": "python -m pdb buggy_script.py",
  "name": "bug-hunt"
}

// 2. Set breakpoint at suspected line
{
  "action": "stdin",
  "id": "bug-hunt",
  "data": "b buggy_script.py:100\r"
}

// 3. Run until breakpoint
{
  "action": "stdin",
  "id": "bug-hunt",
  "data": "c\r"
}

// 4. Inspect variables
{
  "action": "stdin",
  "id": "bug-hunt",
  "data": "pp locals()\r"
}

// 5. Get current state
{
  "action": "stdout",
  "id": "bug-hunt"
}

// 6. Step through suspicious code
{
  "action": "stdin",
  "id": "bug-hunt",
  "data": "n\r"
}

// 7. Check variable changes
{
  "action": "stdout",
  "id": "bug-hunt"
}

Multi-Breakpoint Analysis

// Set multiple breakpoints
{
  "action": "stdin",
  "id": "python-debug",
  "data": "b function_a\r"
}

{
  "action": "stdin",
  "id": "python-debug",
  "data": "b function_b\r"
}

{
  "action": "stdin",
  "id": "python-debug",
  "data": "b function_c\r"
}

// Run and collect state at each breakpoint
{
  "action": "stdin",
  "id": "python-debug",
  "data": "c\r"
}

// Capture state
{
  "action": "stdout",
  "id": "python-debug"
}

// Continue to next breakpoint
{
  "action": "stdin",
  "id": "python-debug",
  "data": "c\r"
}

// Capture state again
{
  "action": "stdout",
  "id": "python-debug"
}

Conditional Debugging

// Set conditional breakpoint
{
  "action": "stdin",
  "id": "python-debug",
  "data": "b process_item, item_id == 'problematic-id'\r"
}

// Run until condition met
{
  "action": "stdin",
  "id": "python-debug",
  "data": "c\r"
}

// Inspect when condition triggers
{
  "action": "stdin",
  "id": "python-debug",
  "data": "pp item\r"
}

{
  "action": "stdout",
  "id": "python-debug"
}

Post-Mortem Debugging

# In your code, catch exceptions and drop into debugger
try:
    risky_operation()
except Exception:
    import pdb; pdb.post_mortem()

// When exception occurs, debugger starts automatically
// terminalcp will capture the interactive session
{
  "action": "stdout",
  "id": "python-debug"
}

// Inspect exception state
{
  "action": "stdin",
  "id": "python-debug",
  "data": "pp sys.exc_info()\r"
}

Stream-Based Monitoring

For long-running debug sessions, use stream mode to capture incremental output:

{
  "action": "stream",
  "id": "python-debug",
  "since_last": true
}

This returns only new output since last check, useful for monitoring debugger progress without blocking.

Best Practices

Effective Breakpoint Strategy

Start broad, then narrow: Set breakpoints at function entry points first
Use conditional breakpoints: Avoid stopping at every iteration in loops
Combine with logging: Use p command output to understand state progression
Clean up: Remove unnecessary breakpoints to avoid clutter

State Capture Timing

Capture state after stepping, not before
Use stdout action after each significant command
For rapid iteration, use stream mode with since_last: true

Managing Multiple Debug Sessions

// Start multiple debuggers for comparison
{
  "action": "start",
  "command": "python -m pdb version_a.py",
  "name": "debug-a"
}

{
  "action": "start",
  "command": "python -m pdb version_b.py",
  "name": "debug-b"
}

// List all active sessions
{
  "action": "list"
}

// Control each independently
{
  "action": "stdin",
  "id": "debug-a",
  "data": "b main\r"
}

{
  "action": "stdin",
  "id": "debug-b",
  "data": "b main\r"
}

Cleanup

Always stop debugger sessions when done:

{
  "action": "stop",
  "id": "python-debug"
}

Common Debugging Workflows

Python Exception Investigation

Run script in debugger
Let it crash or set breakpoint before error
Use w to see stack trace
Use u/d to navigate frames
Use p to inspect variables at each frame
Identify root cause

Memory Leak Detection (C/C++)

Start GDB with program
Set breakpoint at allocation site
Use info proc mappings to see memory layout
Compare memory before/after operations
Use x command to examine memory regions

Race Condition Debugging

Set breakpoints at critical sections
Run multiple debug sessions
Use conditional breakpoints on shared state
Capture timing of variable changes

This skill provides the foundation for AI-driven interactive debugging using terminalcp's real-time PTY capabilities.