Create session

Session Management

# Create session
screen -dmS debug_$ISSUE_ID

# Send commands
screen -S debug_$ISSUE_ID -X stuff "python script.py\n"

# Capture output with history
screen -S debug_$ISSUE_ID -X hardcopy -h /tmp/debug_capture.txt

# Clean up
screen -S debug_$ISSUE_ID -X quit

Live Debugging

# List current code
screen -S debug_$ISSUE_ID -X stuff "l\n"

# Inspect variables
screen -S debug_$ISSUE_ID -X stuff "pp locals()\n"

# Continue execution
screen -S debug_$ISSUE_ID -X stuff "c\n"

CIPDB Integration

Agent-Specific Breakpoints

import cipdb
import os

# Only DebuggerAgent stops here
cipdb.set_trace(os.getenv("AGENT_ID") == "DebuggerAgent")

# ID-based conditional breakpoints
cipdb.set_trace(id="validation_error")
cipdb.set_trace(id="db_connection")
cipdb.set_trace(id="auth_failure")

Environment Control

# Agent identification
export AGENT_ID=DebuggerAgent

# Selective breakpoint activation
export CIPDB_IDS=validation_error,auth_failure

# Disable all breakpoints
export CIPDB_ID=false

Multi-Agent Workflow

1. Issue Identification

# Initial error capture
screen -dmS error_scan
screen -S error_scan -X stuff "python failing_script.py\n"
sleep 2
screen -S error_scan -X hardcopy -h /tmp/initial_error.txt
grep "Traceback\|Error" /tmp/initial_error.txt

2. Breakpoint Insertion

File: problematic_script.py

# Add conditional breakpoints at suspected locations
import cipdb

def validate_input(data):
    cipdb.set_trace(id="input_validation")
    # validation logic here

def database_query(sql):
    cipdb.set_trace(id="db_query") 
    # database code here

3. Targeted Debugging

# Activate specific breakpoints
export CIPDB_IDS=input_validation
export AGENT_ID=DebuggerAgent

# Start debugging session
screen -dmS debug_input
screen -S debug_input -X stuff "python problematic_script.py\n"
sleep 1

# Capture debugger state
screen -S debug_input -X hardcopy -h /tmp/debug_state.txt
tail -20 /tmp/debug_state.txt

4. State Analysis

# Extract current location
grep "^> " /tmp/debug_state.txt | tail -1

# Check variable states
screen -S debug_input -X stuff "pp vars()\n"
sleep 0.5
screen -S debug_input -X hardcopy -h /tmp/vars.txt

5. Hypothesis Testing

# Modify variables in debugger
screen -S debug_input -X stuff "data['field'] = 'corrected_value'\n"

# Continue and observe
screen -S debug_input -X stuff "c\n"
sleep 2
screen -S debug_input -X hardcopy -h /tmp/result.txt

Output Parsing

Session Status Check

# Check if debugger is active
tail -1 /tmp/debug_capture.txt | grep -q "ipdb>" && echo "In debugger"

# Extract current file and line
grep "^> " /tmp/debug_capture.txt | tail -1 | awk '{print $2 ":" $3}'

Error Detection

# Check for exceptions
grep -i "traceback\|error\|exception" /tmp/debug_capture.txt

# Success indicators
grep -i "completed\|success\|passed" /tmp/debug_capture.txt

Agent Coordination

TestAgent Setup

export AGENT_ID=TestAgent
# TestAgent inserts breakpoints but doesn't stop
cipdb.set_trace(id="test_failure", condition=False)

DebuggerAgent Activation

export AGENT_ID=DebuggerAgent  
export CIPDB_IDS=test_failure
# DebuggerAgent activates TestAgent's breakpoints

Best Practices

1. Session Naming

   • Use: debug_${ISSUE_ID}_${TIMESTAMP}
   • Avoid conflicts between concurrent debugging

2. Timing

   • Add sleep 0.5-2s after commands before capture
   • Screen needs time to process

3. Cleanup

   • Run screen -wipe periodically
   • Set CIPDB_ID=false in production

4. Breakpoint IDs

   • Use descriptive names: auth_failure, db_timeout
   • Document ID purposes in code comments

Integration Benefits

• No wrapper complexity - direct screen usage
• CIPDB enables selective debugging per agent
• Multiple agents can debug same codebase simultaneously
• Full observability through screen captures
• Simple environment variable control

The combination provides powerful debugging without architectural overhead.