GDB Debugging Assistant Skill

GDB Debugging Assistant

Overview

A GDB debugging skill designed for AI agents. Combines source code analysis with runtime state inspection using gdb-cli to provide intelligent debugging assistance for C/C++ programs.

When to Use This Skill

Analyze core dumps or crash dumps
Debug running processes with GDB attach
Investigate crashes, deadlocks, or memory issues
Get intelligent debugging assistance with source code context
Debug multi-threaded applications

Do Not Use This Skill When

The task is unrelated to C/C++ debugging
The user needs general-purpose assistance without debugging
No GDB is available (GDB 9.0+ with Python support required)

Prerequisites

# Install gdb-cli
pip install gdb-cli

# Or from GitHub
pip install git+https://github.com/Cerdore/gdb-cli.git

# Verify GDB has Python support
gdb -nx -q -batch -ex "python print('OK')"

Requirements:

Python 3.6.8+
GDB 9.0+ with Python support enabled
Linux OS

How It Works

Step 1: Initialize Debug Session

For core dump analysis:

gdb-cli load --binary <binary_path> --core <core_path> [--gdb-path <gdb_path>]

For live process debugging:

gdb-cli attach --pid <pid> [--binary <binary_path>]

Output: A session_id like "session_id": "a1b2c3". Store this for subsequent commands.

Step 2: Gather Initial Information

SESSION="<session_id>"

# List all threads
gdb-cli threads -s $SESSION

# Get backtrace (with local variables)
gdb-cli bt -s $SESSION --full

# Get registers
gdb-cli registers -s $SESSION

Step 3: Correlate Source Code (CRITICAL)

For each frame in the backtrace:

Extract frame info: {file}:{line} in {function}
Read source context: Get ±20 lines around the crash point
Get local variables: gdb-cli locals-cmd -s $SESSION --frame <N>
Analyze: Correlate code logic with variable values

Example correlation:

Frame #0: process_data() at src/worker.c:87
Source code shows:
  85: Node* node = get_node(id);
  86: if (node == NULL) return;
  87: node->data = value;  <- Crash here

Variables show:
  node = 0x0 (NULL)

Analysis: The NULL check on line 86 didn't catch the issue.

Step 4: Deep Investigation

# Examine variables
gdb-cli eval-cmd -s $SESSION "variable_name"
gdb-cli eval-cmd -s $SESSION "ptr->field"
gdb-cli ptype -s $SESSION "struct_name"

# Memory inspection
gdb-cli memory -s $SESSION "0x7fffffffe000" --size 64

# Disassembly
gdb-cli disasm -s $SESSION --count 20

# Check all threads (for deadlock analysis)
gdb-cli thread-apply -s $SESSION bt --all

# View shared libraries
gdb-cli sharedlibs -s $SESSION

Step 5: Session Management

# List active sessions
gdb-cli sessions

# Check session status
gdb-cli status -s $SESSION

# Stop session (cleanup)
gdb-cli stop -s $SESSION

Common Debugging Patterns

Pattern: Null Pointer Dereference

Indicators:

Crash on memory access instruction
Pointer variable is 0x0

Investigation:

gdb-cli registers -s $SESSION  # Check RIP
gdb-cli eval-cmd -s $SESSION "ptr"  # Check pointer value

Pattern: Deadlock

Indicators:

Multiple threads stuck in lock functions
pthread_mutex_lock in backtrace

Investigation:

gdb-cli thread-apply -s $SESSION bt --all
# Look for circular wait patterns

Pattern: Memory Corruption

Indicators:

Crash in malloc/free
Garbage values in variables

Investigation:

gdb-cli memory -s $SESSION "&variable" --size 128
gdb-cli registers -s $SESSION

Examples

Example 1: Core Dump Analysis

# Load core dump
gdb-cli load --binary ./myapp --core /tmp/core.1234

# Get crash location
gdb-cli bt -s a1b2c3 --full

# Examine crash frame
gdb-cli locals-cmd -s a1b2c3 --frame 0

Example 2: Live Process Debugging

# Attach to stuck server
gdb-cli attach --pid 12345

# Check all threads
gdb-cli threads -s b2c3d4

# Get all backtraces
gdb-cli thread-apply -s b2c3d4 bt --all

Best Practices

Always read source code before drawing conclusions from variable values
Use --range for pagination on large thread counts or deep backtraces
Use ptype to understand complex data structures before examining values
Check all threads for multi-threaded issues
Cross-reference types with source code definitions

Security & Safety Notes

This skill requires GDB access to processes and core dumps
Attaching to processes may require appropriate permissions (sudo, ptrace_scope)
Core dumps may contain sensitive data - handle with care
Only debug processes you have authorization to analyze

Related Skills

@systematic-debugging - General debugging methodology
@test-driven-development - Write tests before implementation

Agent Skills: GDB Debugging Assistant

Install this agent skill to your local

Skill Files