GDB CLI für KI

PyPI version Python License

Ein GDB-Debugging-Tool, das für KI-Agenten (Claude Code, etc.) entwickelt wurde. Verwendet eine Architektur aus "Thin-Client-CLI + GDB-integriertem Python-RPC-Server", die zustandsbehaftetes GDB-Debugging über Bash ermöglicht.

Funktionen

Core-Dump-Analyse: Laden von Core-Dumps mit im Speicher befindlichen Symbolen für Reaktionen im Millisekundenbereich
Live-Attach-Debugging: Anhängen an laufende Prozesse mit Unterstützung für den Non-Stop-Modus
Strukturierte JSON-Ausgabe: Alle Befehle geben JSON mit automatischer Kürzung/Paginierung und Bedienungshinweisen aus
Sicherheitsmechanismen: Befehls-Whitelist, automatische Bereinigung bei Heartbeat-Timeout, Idempotenz-Garantien
Datenbank-optimiert: Scheduler-Locking, Paginierung großer Objekte, Multi-Thread-Kürzung

Anforderungen

Python: 3.6.8+
GDB: 9.0+ mit aktivierter Python-Unterstützung
Betriebssystem: Linux

GDB-Python-Unterstützung prüfen

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

Umgebungsprüfung

gdb-cli env-check


## Quick Start

### 1. Load Core Dump

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

Ausgabe:

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

Beim Laden einer großen Binärdatei oder eines Core-Files, warten Sie, bis die Sitzung bereit ist:

gdb-cli status -s f465d650

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

Wenn das Standard-GDB Ihres Systems keine Python-Unterstützung hat, geben Sie diese mit --gdb-path an:
gdb-cli load --binary ./my_program --core ./core.12345 \
  --gdb-path /opt/rh/gcc-toolset-13/root/usr/bin/gdb

2. Debugging-Operationen

Alle Operationen verwenden --session / -s, um die Sitzungs-ID anzugeben:

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

# 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

Vollständige Befehlsreferenz

load — Core-Dump laden

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 kehrt sofort mit "status": "loading" zurück, sobald der RPC-Server erreichbar ist. Verwenden Sie gdb-cli status -s <session> und warten Sie auf "state": "ready", bevor Sie umfangreiche Inspektionsbefehle ausführen.

attach — An Prozess anhängen

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 — Threads auflisten

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 — Ausdruck auswerten

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

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

eval-element — Auf Array-/Container-Elemente zugreifen

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

exec — Unformatierten GDB-Befehl ausführen

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

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

thread-apply — Batch-Thread-Operationen

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

Ausgabebeispiele

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
}

Sicherheitsmechanismen

Befehls-Whitelist (Attach-Modus)

Sicherheitsstufe	Erlaubte Befehle
`readonly` (Standard)	bt, info, print, threads, locals, frame
`readwrite`	+ set variable
`full`	+ call, continue, step, next

quit, kill, shell, signal sind immer blockiert.

Heartbeat-Timeout

Standardmäßig wird die Verbindung nach 10 Minuten Inaktivität automatisch getrennt und beendet. Konfigurierbar über --timeout.

Idempotenz

Pro PID / Core-File ist nur eine Sitzung zulässig. Wiederholtes Laden/Anhängen gibt die bestehende session_id zurück.

Cross-Machine Core-Dump-Debugging

Bei der Analyse von Core-Dumps von anderen Maschinen können die Pfade zu gemeinsam genutzten Bibliotheken abweichen:

# 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

Entwicklung

Projektstruktur

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

Tests ausführen

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

End-to-End-Tests

Erfordert GDB mit Python-Unterstützung. Verwenden Sie das Crash-Test-Programm 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

Bekannte Einschränkungen

Keine target remote-Unterstützung (verwenden Sie SSH für Remote-Debugging, siehe unten)
Keine Unterstützung für Multi-Inferior-Debugging
GDB 12.x Guile Pretty-Printer sind nicht Thread-sicher, Workaround über format_string(raw=True)
Die eingebettete Python-Version von GDB kann älter sein (z. B. 3.6.8), der Code verfügt über Kompatibilitätsbehandlungen

Remote-Debugging via SSH

Installieren und ausführen auf der Remote-Maschine mit einem Befehl:

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

Oder zuerst installieren, dann debuggen:

# 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

Dieses Projekt enthält ein gdb-cli-Skill für Claude Code, das intelligente Debugging-Unterstützung bietet, indem es Quellcode-Analyse mit der Inspektion des Laufzeitzustands kombiniert.

Skill installieren

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

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

Funktionen

Quellcode-Korrelation: Liest automatisch Quelldateien rund um Absturzpunkte
Deadlock-Erkennung: Identifiziert zirkuläre Warte-Muster in Multi-Thread-Programmen
Sicherheitswarnungen: Warnt vor Risiken in Produktionsumgebungen beim Anhängen an Live-Prozesse
Strukturierte Berichte: Generiert Analysen mit Hypothesen zur Grundursache und nächsten Schritten

Siehe skills/README.md für weitere Details.

Lizenz

Apache License 2.0

GDB CLI für KI

Funktionen

Anforderungen

GDB-Python-Unterstützung prüfen

Installation

Umgebungsprüfung

2. Debugging-Operationen

3. Sitzungsverwaltung

4. Live-Attach-Debugging

Vollständige Befehlsreferenz

load — Core-Dump laden

attach — An Prozess anhängen

threads — Threads auflisten

bt — Backtrace

eval-cmd — Ausdruck auswerten

eval-element — Auf Array-/Container-Elemente zugreifen

exec — Unformatierten GDB-Befehl ausführen

thread-apply — Batch-Thread-Operationen

Ausgabebeispiele

threads

eval-cmd

bt

Sicherheitsmechanismen

Befehls-Whitelist (Attach-Modus)

Heartbeat-Timeout

Idempotenz

Cross-Machine Core-Dump-Debugging

Entwicklung

Projektstruktur

Tests ausführen

End-to-End-Tests

Bekannte Einschränkungen

Remote-Debugging via SSH

Claude Code Skills

Skill installieren

Verwendung in Claude Code

Funktionen

Lizenz

Resources

Latest Blog Posts

MCP directory API