C/C++ AI Debugger Skill

AI-powered debugging skill for C/C++ projects with GDB/LLDB support.

Features

• 🔍 Smart Breakpoint Management - Set, remove, enable/disable breakpoints with conditional support
• 📊 Variable Inspection - View local and global variables, evaluate expressions
• 🎯 Step Execution Control - Run, step, next, finish, continue, pause, terminate
• 🔄 Multi-Session Support - Manage multiple debugging sessions simultaneously
• 🤖 AI-Assisted Debugging - JSON-based command interface for AI integration
• 🌍 Cross-Platform - Works with GDB (Linux/macOS/Windows MinGW) and LLDB (macOS/Windows)

Installation

Prerequisites

• Python 3.8 or higher
• GDB 9.0+ or LLDB 12.0+

Install Dependencies

# Install Python dependencies
pip install pygdbmi

# Optional: for LLDB support
# LLDB Python module comes with Xcode (macOS) or LLVM installation

Install GDB

# Linux (Ubuntu/Debian)
sudo apt-get install gdb

# macOS
brew install gdb

# Windows (MinGW)
pacman -S mingw-w64-x86_64-gdb

Install LLDB

# macOS (comes with Xcode)
xcode-select --install

# Linux
sudo apt-get install lldb

# Windows
# Download and install LLVM from https://releases.llvm.org/

Quick Start

Basic Usage

from src.debugger import AIDebugger
import json

# Initialize debugger
debugger = AIDebugger()

# Create a debug session
result = debugger.execute_command(json.dumps({
    'action': 'create_session',
    'params': {
        'program_path': './my_program'
    }
}))

response = json.loads(result)
session_id = response['result']['session_id']

# Set a breakpoint
debugger.execute_command(json.dumps({
    'action': 'set_breakpoint',
    'params': {
        'session_id': session_id,
        'location': 'main.cpp:42'
    }
}))

# Run the program
debugger.execute_command(json.dumps({
    'action': 'run',
    'params': {
        'session_id': session_id
    }
}))

# Get variables
result = debugger.execute_command(json.dumps({
    'action': 'get_variables',
    'params': {
        'session_id': session_id,
        'scope': 'local'
    }
}))

# Close session
debugger.execute_command(json.dumps({
    'action': 'close_session',
    'params': {
        'session_id': session_id
    }
}))

Supported Actions

Session Management

Action	Description	Required Parameters
create_session	Create a new debugging session	program_path
close_session	Close a debugging session	session_id
list_sessions	List all active sessions	-

Breakpoint Management

Action	Description	Required Parameters
set_breakpoint	Set a breakpoint	session_id, location
remove_breakpoint	Remove a breakpoint	session_id, breakpoint_id
enable_breakpoint	Enable a breakpoint	session_id, breakpoint_id
disable_breakpoint	Disable a breakpoint	session_id, breakpoint_id
list_breakpoints	List all breakpoints	session_id

Execution Control

Action	Description	Required Parameters
run	Start/restart program	session_id
continue	Continue execution	session_id
step	Step into function	session_id
next	Step over function	session_id
finish	Execute until return	session_id
pause	Pause execution	session_id
terminate	Terminate program	session_id

Inspection

Action	Description	Required Parameters
get_variables	Get variable values	session_id
get_backtrace	Get call stack	session_id
evaluate_expression	Evaluate expression	session_id, expression
get_registers	Get CPU registers	session_id
read_memory	Read memory	session_id, address
get_current_location	Get current location	session_id
get_context	Get full context	session_id

Breakpoint Location Formats

Breakpoints can be set using various location formats:

# File and line number
'location': 'main.cpp:42'

# Function name
'location': 'main'

# Class method
'location': 'MyClass::myMethod'

# File and function
'location': 'main.cpp:main'

# Memory address
'location': '*0x4005a0'

Conditional Breakpoints

debugger.execute_command(json.dumps({
    'action': 'set_breakpoint',
    'params': {
        'session_id': session_id,
        'location': 'main.cpp:42',
        'condition': 'x > 10 && y < 100'
    }
}))

Response Format

All commands return JSON responses:

Success:

{
    "success": true,
    "result": {
        // Action-specific result
    }
}

Error:

{
    "success": false,
    "error": "Error description"
}

Examples

See the examples/ directory for complete examples:

• simple_breakpoint.py - Basic debugging workflow
• multi_session.py - Managing multiple sessions

Running Tests

# Run unit tests
pytest tests/

# Run integration tests (requires GDB/LLDB)
pytest tests/ --run-integration

Project Structure

cpp-debugger-skill/
├── SKILL.md              # Trae skill definition
├── README.md             # This file
├── requirements.txt      # Python dependencies
├── setup.py              # Setup script
├── src/
│   ├── __init__.py
│   ├── debugger.py       # Main AI interface
│   ├── session.py        # Session management
│   ├── context.py        # Debug context
│   └── adapters/
│       ├── __init__.py
│       ├── base.py       # Abstract base class
│       ├── gdb_adapter.py    # GDB implementation
│       ├── lldb_adapter.py   # LLDB implementation
│       └── factory.py    # Debugger factory
├── tests/
│   ├── __init__.py
│   └── test_debugger.py  # Unit tests
├── examples/
│   ├── simple_breakpoint.py
│   └── multi_session.py
└── docs/
    ├── getting-started.md
    ├── api-reference.md
    └── examples.md

Troubleshooting

GDB Not Found

# Linux
sudo apt-get install gdb

# macOS
brew install gdb

# Windows (MinGW)
pacman -S mingw-w64-x86_64-gdb

Permission Denied (Linux)

# Temporary fix
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

# Permanent fix (add to /etc/sysctl.d/10-ptrace.conf)
kernel.yama.ptrace_scope = 0

LLDB Python Module Not Found

# macOS - Install Xcode command line tools
xcode-select --install

# Linux - Install LLDB development package
sudo apt-get install python3-lldb-12

# Windows - Install LLVM with Python bindings
# Download from https://releases.llvm.org/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Author

Your Name (your.email@example.com)

Acknowledgments

• pygdbmi - GDB Machine Interface Python wrapper
• LLDB - LLVM Debugger
• GDB - GNU Debugger