AI向けGDB CLI

PyPI version Python License

AIエージェント（Claude Codeなど）向けに設計されたGDBデバッグツールです。「シンクライアントCLI + GDB組み込みPython RPCサーバー」アーキテクチャを採用し、Bashを通じてステートフルなGDBデバッグを可能にします。

特徴

コアダンプ解析: メモリ上に常駐するシンボルを使用してコアダンプを読み込み、ミリ秒単位の応答を実現
ライブアタッチデバッグ: ノンストップモードをサポートし、実行中のプロセスにアタッチ可能
構造化JSON出力: すべてのコマンドがJSONを出力し、自動切り詰め/ページネーションおよび操作ヒントを提供
セキュリティメカニズム: コマンドホワイトリスト、ハートビートタイムアウトによる自動クリーンアップ、冪等性の保証
データベース最適化: スケジューラロック、ラージオブジェクトのページネーション、マルチスレッドの切り詰め

要件

Python: 3.6.8以上
GDB: 9.0以上（Pythonサポートが有効であること）
OS: Linux

GDBのPythonサポート確認

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

インストール

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

環境チェック

gdb-cli env-check


## Quick Start

### 1. Load Core Dump

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

出力:

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

大きなバイナリやコアファイルを読み込む際は、セッションが準備完了になるまでポーリングします:

gdb-cli status -s f465d650

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

システムのデフォルトGDBにPythonサポートがない場合は、--gdb-pathで指定してください:
gdb-cli load --binary ./my_program --core ./core.12345 \
  --gdb-path /opt/rh/gcc-toolset-13/root/usr/bin/gdb

2. デバッグ操作

すべての操作で --session / -s を使用してセッション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. セッション管理

# List all active sessions
gdb-cli sessions

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

4. ライブアタッチデバッグ

# 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

コマンドリファレンス

load — コアダンプの読み込み

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は、RPCサーバーが到達可能になると直ちに"status": "loading"を返します。詳細な調査コマンドを実行する前に、gdb-cli status -s <session>を使用して"state": "ready"になるまで待機してください。

attach — プロセスへのアタッチ

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 — スレッド一覧

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 — バックトレース

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 — 式の評価

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

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

eval-element — 配列/コンテナ要素へのアクセス

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

exec — GDBコマンドの直接実行

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

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

thread-apply — スレッド操作のバッチ処理

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

出力例

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
}

セキュリティメカニズム

コマンドホワイトリスト（アタッチモード）

安全レベル	許可されるコマンド
`readonly` (デフォルト)	bt, info, print, threads, locals, frame
`readwrite`	+ set variable
`full`	+ call, continue, step, next

quit, kill, shell, signal は常にブロックされます。

ハートビートタイムアウト

デフォルトでは、10分間操作がないと自動的にデタッチして終了します。--timeoutで設定可能です。

冪等性

PIDまたはコアファイルごとに1つのセッションのみ許可されます。繰り返しload/attachを実行すると、既存のsession_idが返されます。

クロスマシンでのコアダンプデバッグ

他のマシンからコアダンプを解析する場合、共有ライブラリのパスが異なることがあります:

# 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

開発

プロジェクト構造

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

テストの実行

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

エンドツーエンドテスト

Pythonサポート付きのGDBが必要です。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

既知の制限事項

target remote サポートなし（リモートデバッグにはSSHを使用してください。下記参照）
マルチインフェリアデバッグのサポートなし
GDB 12.xのGuileプリティプリンタはスレッドセーフではありません。format_string(raw=True)で回避してください
GDB組み込みのPythonバージョンが古い場合（例: 3.6.8）があります。コードには互換性処理が含まれています

SSH経由のリモートデバッグ

リモートマシンにインストールして1コマンドで実行:

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

または、先にインストールしてからデバッグ:

# 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スキル

本プロジェクトには、Claude Code用の gdb-cliスキル が含まれています。ソースコード解析と実行時の状態検査を組み合わせることで、インテリジェントなデバッグ支援を提供します。

スキルのインストール

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

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.

特徴

ソースコード相関: クラッシュポイント周辺のソースファイルを自動的に読み込みます
デッドロック検出: マルチスレッドプログラムにおける循環待機パターンを特定します
安全警告: ライブプロセスにアタッチする際、本番環境のリスクについて警告します
構造化レポート: 根本原因の仮説と次のステップを含む分析を生成します

詳細は skills/README.md を参照してください。

ライセンス

Apache License 2.0