Which integrations are available for this server?

Enables AI agents to debug C++ programs by providing structured access to GDB features like expression evaluation, thread management, and backtrace analysis for live processes and core dumps.

GDB CLI for AI

PyPI version Python License

A GDB debugging tool designed for AI Agents (Claude Code, etc.). Uses a "thin client CLI + GDB built-in Python RPC Server" architecture, enabling stateful GDB debugging through Bash.

Features

Core Dump Analysis: Load core dumps with symbols resident in memory for millisecond-level response
Live Attach Debugging: Attach to running processes with non-stop mode support
Structured JSON Output: All commands output JSON with automatic truncation/pagination and operation hints
Security Mechanisms: Command whitelist, heartbeat timeout auto-cleanup, idempotency guarantees
Database-Optimized: scheduler-locking, large object pagination, multi-thread truncation

Requirements

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

Check GDB Python Support

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

# If system GDB lacks Python, check GCC Toolset (RHEL/CentOS)
/opt/rh/gcc-toolset-13/root/usr/bin/gdb -nx -q -batch -ex "python print('OK')"

Installation

# Install from PyPI
pip install gdb-cli

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

# Or clone and install locally
git clone https://github.com/Cerdore/gdb-cli.git
cd gdb-cli
pip install -e .

Environment check

gdb-cli env-check


## Quick Start

### 1. Load Core Dump

```bash
gdb-cli load --binary ./my_program --core ./core.12345

Output:

{
  "session_id": "f465d650",
  "mode": "core",
  "binary": "./my_program",
  "core": "./core.12345",
  "gdb_pid": 12345,
  "status": "loading"
}

When loading a large binary or core file, poll until the session becomes ready:

gdb-cli status -s f465d650

{
  "session_id": "f465d650",
  "state": "ready",
  "mode": "core",
  "binary": "./my_program"
}

If your system's default GDB doesn't have Python support, specify it with --gdb-path:
gdb-cli load --binary ./my_program --core ./core.12345 \
  --gdb-path /opt/rh/gcc-toolset-13/root/usr/bin/gdb

2. Debugging Operations

All operations use --session / -s to specify the session ID:

SESSION="f465d650"

# List threads
gdb-cli threads -s $SESSION

# Get backtrace (default: current thread)
gdb-cli bt -s $SESSION

# Get backtrace for a specific thread
gdb-cli bt -s $SESSION --thread 3

# Evaluate C/C++ expressions
gdb-cli eval-cmd -s $SESSION "my_struct->field"

# Access array elements
gdb-cli eval-element -s $SESSION "my_array" --index 5

# View local variables
gdb-cli locals-cmd -s $SESSION

# Execute raw GDB commands
gdb-cli exec -s $SESSION "info registers"

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

3. Session Management

# List all active sessions
gdb-cli sessions

# Stop a session
gdb-cli stop -s $SESSION

4. Live Attach Debugging

# Attach to a running process (default: scheduler-locking + non-stop)
gdb-cli attach --pid 9876

# Attach with symbol file
gdb-cli attach --pid 9876 --binary ./my_program

# Allow memory modification and function calls
gdb-cli attach --pid 9876 --allow-write --allow-call

Full Command Reference

load — Load Core Dump

gdb-cli load --binary <path> --core <path> [options]

  --binary, -b      Executable file path (required)
  --core, -c        Core dump file path (required)
  --sysroot         sysroot path (for cross-machine debugging)
  --solib-prefix    Shared library prefix
  --source-dir      Source code directory
  --timeout         Heartbeat timeout in seconds (default: 600)
  --gdb-path        GDB executable path (default: "gdb")

load returns immediately with "status": "loading" after the RPC server becomes reachable. Use gdb-cli status -s <session> and wait for "state": "ready" before heavy inspection commands.

attach — Attach to Process

gdb-cli attach --pid <pid> [options]

  --pid, -p               Process PID (required)
  --binary                Executable file path (optional)
  --scheduler-locking     Enable scheduler-locking (default: true)
  --non-stop              Enable non-stop mode (default: true)
  --timeout               Heartbeat timeout in seconds (default: 600)
  --allow-write           Allow memory modification
  --allow-call            Allow function calls

threads — List Threads

gdb-cli threads -s <session> [options]

  --range           Thread range, e.g., "3-10"
  --limit           Maximum return count (default: 20)
  --filter-state    Filter by state ("running" / "stopped")

bt — Backtrace

gdb-cli bt -s <session> [options]

  --thread, -t      Specify thread ID
  --limit           Maximum frame count (default: 30)
  --full            Include local variables
  --range           Frame range, e.g., "5-15"

eval-cmd — Evaluate Expression

gdb-cli eval-cmd -s <session> <expr> [options]

  --max-depth       Recursion depth limit (default: 3)
  --max-elements    Array element limit (default: 50)

eval-element — Access Array/Container Elements

gdb-cli eval-element -s <session> <expr> --index <N>

exec — Execute Raw GDB Command

gdb-cli exec -s <session> <command>

  --safety-level    Safety level (readonly / readwrite / full)

thread-apply — Batch Thread Operations

gdb-cli thread-apply -s <session> <command> --all
gdb-cli thread-apply -s <session> <command> --threads "1,3,5"

Output Examples

threads

{
  "threads": [
    {"id": 1, "global_id": 1, "state": "stopped"},
    {"id": 2, "global_id": 2, "state": "stopped"}
  ],
  "total_count": 5,
  "truncated": true,
  "current_thread": {"id": 1, "global_id": 1, "state": "stopped"},
  "hint": "use 'threads --range START-END' for specific threads"
}

eval-cmd

{
  "expression": "(int)5+3",
  "value": 8,
  "type": "int",
  "size": 4
}

bt

{
  "frames": [
    {"number": 0, "function": "crash_thread", "address": "0x400a1c", "file": "test.c", "line": 42},
    {"number": 1, "function": "start_thread", "address": "0x7f3fa2e13fa"}
  ],
  "total_count": 2,
  "truncated": false
}

Security Mechanisms

Command Whitelist (Attach Mode)

Safety Level	Allowed Commands
`readonly` (default)	bt, info, print, threads, locals, frame
`readwrite`	+ set variable
`full`	+ call, continue, step, next

quit, kill, shell, signal are always blocked.

Heartbeat Timeout

Automatically detaches and quits after 10 minutes of inactivity by default. Configurable via --timeout.

Idempotency

Only one session per PID / Core file is allowed. Repeated load/attach returns the existing session_id.

Cross-Machine Core Dump Debugging

When analyzing core dumps from other machines, shared library paths may differ:

# Set sysroot (path prefix replacement)
gdb-cli load --binary ./my_program --core ./core.1234 \
  --sysroot /path/to/target/rootfs

# Set source directory (for source-level debugging)
gdb-cli load --binary ./my_program --core ./core.1234 \
  --source-dir /path/to/source

Development

Project Structure

src/gdb_cli/
├── cli.py              # CLI entry point (Click)
├── client.py           # Unix Socket client
├── launcher.py         # GDB process launcher
├── session.py          # Session metadata management
├── safety.py           # Command whitelist filter
├── formatters.py       # JSON output formatting
├── env_check.py        # Environment check
├── errors.py           # Error classification
└── gdb_server/
    ├── gdb_rpc_server.py   # RPC Server core
    ├── handlers.py         # Command handlers
    ├── value_formatter.py  # gdb.Value serialization
    └── heartbeat.py         # Heartbeat timeout management

skills/
└── gdb-cli/               # Claude Code skill for intelligent debugging
    ├── SKILL.md            # Skill definition
    └── evals/              # Test cases for skill evaluation

Run Tests

pip install -e ".[dev]"
pytest tests/ -v

End-to-End Testing

Requires GDB with Python support. Use the crash test program in tests/crash_test/:

# Compile test program
cd tests/crash_test
gcc -g -pthread -o crash_test crash_test_c.c

# Generate coredump
ulimit -c unlimited
./crash_test  # Will SIGSEGV

# Find core file
ls /path/to/core_dumps/core-crash_test-*

# Run E2E test
gdb-cli load --binary ./crash_test --core /path/to/core \
  --gdb-path /opt/rh/gcc-toolset-13/root/usr/bin/gdb

Known Limitations

No target remote support (use SSH for remote debugging, see below)
No multi-inferior debugging support
GDB 12.x Guile pretty printers are not thread-safe, workaround via format_string(raw=True)
GDB embedded Python version may be older (e.g., 3.6.8), code has compatibility handling

Remote Debugging via SSH

Install and run on remote machine in one command:

ssh user@remote-host "pip install git+https://github.com/Cerdore/gdb-cli.git && gdb-cli load --binary ./my_program --core ./core.12345"

Or install first, then debug:

# Install on remote
ssh user@remote-host "pip install git+https://github.com/Cerdore/gdb-cli.git"

# Run debugging
ssh user@remote-host "gdb-cli load --binary ./my_program --core ./core.12345"

Claude Code Skills

This project includes a gdb-cli skill for Claude Code that provides intelligent debugging assistance by combining source code analysis with runtime state inspection.

Install the Skill

bunx skills add https://github.com/Cerdore/gdb-cli --skill=gdb-cli

Usage in Claude Code

/gdb-cli

# Or describe your debugging need:
I have a core dump at ./core.1234 and binary at ./myapp. Help me debug it.

Features

Source Code Correlation: Automatically reads source files around crash points
Deadlock Detection: Identifies circular wait patterns in multi-threaded programs
Safety Warnings: Alerts about production environment risks when attaching to live processes
Structured Reports: Generates analysis with root cause hypotheses and next steps

See skills/README.md for more details.

License

Apache License 2.0

GDB CLI for AI

Features

Requirements

Check GDB Python Support

Installation

Environment check

2. Debugging Operations

3. Session Management

4. Live Attach Debugging

Full Command Reference

load — Load Core Dump

attach — Attach to Process

threads — List Threads

bt — Backtrace

eval-cmd — Evaluate Expression

eval-element — Access Array/Container Elements

exec — Execute Raw GDB Command

thread-apply — Batch Thread Operations

Output Examples

threads

eval-cmd

bt

Security Mechanisms

Command Whitelist (Attach Mode)

Heartbeat Timeout

Idempotency

Cross-Machine Core Dump Debugging

Development

Project Structure

Run Tests

End-to-End Testing

Known Limitations

Remote Debugging via SSH

Claude Code Skills

Install the Skill

Usage in Claude Code

Features

License

Maintenance

Resources

Latest Blog Posts

MCP directory API