AI를 위한 GDB CLI

PyPI version Python License

AI 에이전트(Claude Code 등)를 위해 설계된 GDB 디버깅 도구입니다. "씬 클라이언트 CLI + GDB 내장 Python RPC 서버" 아키텍처를 사용하여 Bash를 통해 상태 유지(stateful) 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/코어 파일당 하나의 세션만 허용됩니다. 반복적인 로드/어태치는 기존 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 사용)
멀티 인페리어(multi-inferior) 디버깅 지원 안 함
GDB 12.x Guile pretty printer는 스레드 안전하지 않음, format_string(raw=True)로 우회 가능
GDB 내장 Python 버전이 오래되었을 수 있음(예: 3.6.8), 코드에 호환성 처리 포함됨

SSH를 통한 원격 디버깅

한 번의 명령으로 원격 기기에 설치 및 실행:

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

AI를 위한 GDB CLI

주요 기능

요구 사항

GDB Python 지원 확인

설치

환경 확인

2. 디버깅 작업

3. 세션 관리

4. 라이브 어태치 디버깅

전체 명령 참조

load — 코어 덤프 로드

attach — 프로세스에 어태치

threads — 스레드 목록

bt — 백트레이스

eval-cmd — 표현식 평가

eval-element — 배열/컨테이너 요소 접근

exec — 원시 GDB 명령 실행

thread-apply — 배치 스레드 작업

출력 예시

threads

eval-cmd

bt

보안 메커니즘

명령 화이트리스트 (어태치 모드)

하트비트 타임아웃

멱등성

타 기기 코어 덤프 디버깅

개발

프로젝트 구조

테스트 실행

엔드 투 엔드 테스트

알려진 제한 사항

SSH를 통한 원격 디버깅

Claude Code 스킬

스킬 설치

Claude Code에서 사용

주요 기능

라이선스

Resources

Latest Blog Posts

MCP directory API