GDB CLI para IA

Versión de PyPI Python Licencia

Una herramienta de depuración GDB diseñada para agentes de IA (Claude Code, etc.). Utiliza una arquitectura de "CLI de cliente ligero + servidor RPC de Python integrado en GDB", lo que permite la depuración GDB con estado a través de Bash.

Características

Análisis de volcado de memoria (Core Dump): Carga volcados de memoria con símbolos residentes en la memoria para una respuesta a nivel de milisegundos
Depuración con adjunción en vivo: Adjuntar a procesos en ejecución con soporte para modo sin interrupción
Salida JSON estructurada: Todos los comandos generan JSON con truncamiento/paginación automática y sugerencias de operación
Mecanismos de seguridad: Lista blanca de comandos, limpieza automática por tiempo de espera de latido, garantías de idempotencia
Optimizado para bases de datos: bloqueo de programador, paginación de objetos grandes, truncamiento multihilo

Requisitos

Python: 3.6.8+
GDB: 9.0+ con soporte de Python habilitado
SO: Linux

Comprobar el soporte de Python en GDB

# 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')"

Instalación

# 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 .

Comprobación del entorno

gdb-cli env-check


## Quick Start

### 1. Load Core Dump

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

Salida:

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

Al cargar un binario grande o un archivo core, sondee hasta que la sesión esté lista:

gdb-cli status -s f465d650

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

Si el GDB predeterminado de su sistema no tiene soporte para Python, especifíquelo con --gdb-path:
gdb-cli load --binary ./my_program --core ./core.12345 \
  --gdb-path /opt/rh/gcc-toolset-13/root/usr/bin/gdb

2. Operaciones de depuración

Todas las operaciones utilizan --session / -s para especificar el ID de sesión:

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. Gestión de sesiones

# List all active sessions
gdb-cli sessions

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

4. Depuración con adjunción en vivo

# 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

Referencia completa de comandos

load — Cargar volcado de memoria (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 devuelve inmediatamente un "status": "loading" una vez que el servidor RPC es accesible. Use gdb-cli status -s <session> y espere a que aparezca "state": "ready" antes de ejecutar comandos de inspección pesados.

attach — Adjuntar a un proceso

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 — Listar hilos

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 (seguimiento de pila)

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 — Evaluar expresión

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

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

eval-element — Acceder a elementos de matriz/contenedor

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

exec — Ejecutar comando GDB sin procesar

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

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

thread-apply — Operaciones de hilo por lotes

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

Ejemplos de salida

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
}

Mecanismos de seguridad

Lista blanca de comandos (Modo adjuntar)

Nivel de seguridad	Comandos permitidos
`readonly` (predeterminado)	bt, info, print, threads, locals, frame
`readwrite`	+ set variable
`full`	+ call, continue, step, next

quit, kill, shell, signal están siempre bloqueados.

Tiempo de espera de latido (Heartbeat)

Se desconecta y cierra automáticamente después de 10 minutos de inactividad de forma predeterminada. Configurable mediante --timeout.

Idempotencia

Solo se permite una sesión por PID / archivo Core. La carga/adjunción repetida devuelve el session_id existente.

Depuración de volcados de memoria entre máquinas

Al analizar volcados de memoria de otras máquinas, las rutas de las bibliotecas compartidas pueden diferir:

# 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

Desarrollo

Estructura del proyecto

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

Ejecutar pruebas

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

Pruebas de extremo a extremo

Requiere GDB con soporte para Python. Utilice el programa de prueba de fallos en 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

Limitaciones conocidas

No hay soporte para target remote (use SSH para depuración remota, ver más abajo)
No hay soporte para depuración de múltiples inferiores
Los pretty printers de Guile en GDB 12.x no son seguros para hilos, solución alternativa mediante format_string(raw=True)
La versión de Python integrada en GDB puede ser antigua (p. ej., 3.6.8), el código tiene manejo de compatibilidad

Depuración remota mediante SSH

Instale y ejecute en la máquina remota con un solo comando:

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

O instale primero y luego depure:

# 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"

Habilidades de Claude Code

Este proyecto incluye una habilidad gdb-cli para Claude Code que proporciona asistencia de depuración inteligente combinando el análisis del código fuente con la inspección del estado en tiempo de ejecución.

Instalar la habilidad

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

Uso en 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.

Características

Correlación de código fuente: Lee automáticamente los archivos fuente alrededor de los puntos de fallo
Detección de interbloqueo (Deadlock): Identifica patrones de espera circular en programas multihilo
Advertencias de seguridad: Alerta sobre riesgos en entornos de producción al adjuntar a procesos en vivo
Informes estructurados: Genera análisis con hipótesis de causa raíz y próximos pasos

Consulte skills/README.md para obtener más detalles.

Licencia

Licencia Apache 2.0

GDB CLI para IA

Características

Requisitos

Comprobar el soporte de Python en GDB

Instalación

Comprobación del entorno

2. Operaciones de depuración

3. Gestión de sesiones

4. Depuración con adjunción en vivo

Referencia completa de comandos

load — Cargar volcado de memoria (Core Dump)

attach — Adjuntar a un proceso

threads — Listar hilos

bt — Backtrace (seguimiento de pila)

eval-cmd — Evaluar expresión

eval-element — Acceder a elementos de matriz/contenedor

exec — Ejecutar comando GDB sin procesar

thread-apply — Operaciones de hilo por lotes

Ejemplos de salida

threads

eval-cmd

bt

Mecanismos de seguridad

Lista blanca de comandos (Modo adjuntar)

Tiempo de espera de latido (Heartbeat)

Idempotencia

Depuración de volcados de memoria entre máquinas

Desarrollo

Estructura del proyecto

Ejecutar pruebas

Pruebas de extremo a extremo

Limitaciones conocidas

Depuración remota mediante SSH

Habilidades de Claude Code

Instalar la habilidad

Uso en Claude Code

Características

Licencia

Resources

Latest Blog Posts

MCP directory API