llmdbg

Minimal LLDB DAP MCP server for LLM pair debugging on macOS.

Requirements

• macOS
• LLDB Debug Adapter Protocol (DAP), via xcrun lldb-dap
• Python 3.10+

Quick start

uv sync --group dev

# Launch a program, stop on entry, and print a snapshot
uv run llmdbg state --program /path/to/binary --args arg1 arg2

Example output (truncated):

{
  "session": {
    "program": "/path/to/binary",
    "pid": 12345,
    "journal": "/Users/you/.llmdbg/sessions/<session-id>.jsonl"
  },
  "process": {
    "state": "stopped",
    "stop_reason": "exception",
    "signal": "SIGSTOP"
  },
  "frame": {
    "function": "_dyld_start",
    "pc": "0x1000109C0"
  },
  "registers": {
    "pc": "0x00000001000109c0 dyld`_dyld_start",
    "sp": "0x000000016fdff128 -> 0x0000000100000000"
  }
}

MCP server

# Start MCP server on stdio
uv run llmdbg-mcp

Architecture

See docs/architecture.md.

MCP usage

Register with Codex:

codex mcp add llmdbg -- uv run llmdbg-mcp

This works with any MCP-capable client. Codex is just one option.

Optional: pin the server working directory in ~/.codex/config.toml:

[mcp_servers.llmdbg]
command = "uv"
args = ["run", "llmdbg-mcp"]
cwd = "/path/to/llmdbg"

Example prompt for root-cause analysis:

Use the llmdbg MCP server to run /path/to/binary as a black-box program.
If it crashes, provide a detailed root-cause analysis with faulting instruction,
signal/stop reason, top stack frames, key registers, and memory near the PC/SP.
If it exits normally, say so.

Skills

This repo includes a sample Codex skill definition at skills/llmdbg-rca/SKILL.md for crash RCA workflows. Copy it into your Codex skills directory if you want to use it directly.

KB

kb/ (knowledge base) is reserved for target-specific notes, crash patterns, and LLDB helper scripts. Use subfolders per target (for example, kb/<target>/).

MCP tools

Tool	Description
session_start(program, args?, env?, cwd?, stop_on_entry?, timeout?)	Start a new lldb-dap session.
session_attach(pid, timeout?)	Attach to an existing PID.
session_close()	Disconnect + terminate the session.
status()	Lightweight session status (pid, last stop reason, journal path).
state(max_stack?, thread_id?, frame_id?, all_threads?)	Structured stop snapshot (frame/regs/locals/stack/disasm), optionally selecting thread/frame and summarizing all threads.
crash_bundle(thread_id?, frame_id?, max_stack?, all_threads?, mem_before?, mem_after?, journal_tail?)	Snapshot plus memory around PC/SP/fault and recent journal entries.
exec(command, frame_id?)	Run a raw LLDB command via DAP evaluate.
continue_exec(timeout?)	Continue and wait for stop/termination.
step_over(timeout?)	Step over and wait for stop/termination.
step_in(timeout?)	Step in and wait for stop/termination.
step_out(timeout?)	Step out and wait for stop/termination.
break_set(location, condition?, hit_count?, log_message?)	Set breakpoint by function name or file:line[:col] (supports conditions and logpoints for source breakpoints).
break_list()	List configured breakpoints (source + function).
break_clear(location?)	Clear one breakpoint (by location) or clear all if omitted.
exception_break_filters()	List adapter-supported exception breakpoint filters.
exception_break_set(filters?, signals?, stop?, notify?, pass_to_process?, clear_signals?)	Enable exception filters and/or configure unix signal handling (LLDB process handle).
watch_set(expression, size?, access?)	Set a watchpoint (LLDB watchpoint set expression).
data_break_info(name, scope?, thread_id?, frame_id?)	Resolve a variable name into a DAP dataId (via dataBreakpointInfo).
data_break_set(data_id?, name?, scope?, thread_id?, frame_id?, access_type?, condition?, hit_count?)	Set a DAP data breakpoint (via setDataBreakpoints).
data_break_list()	List configured DAP data breakpoints.
data_break_clear(data_id?)	Clear one DAP data breakpoint (by data_id) or clear all if omitted.
threads()	List threads and the last stop reason (when known).
stack(thread_id, levels?)	Stack trace for a specific thread.
bt_all(levels?, max_threads?)	Stack traces for up to N threads.
modules(start_module?, module_count?)	List loaded modules/images.
disasm(address, instruction_count?, instruction_offset?)	Disassemble around an address.
memory_regions(address?, max_lines?)	Show memory region(s) (includes parsed regions when possible).
source_context(file, line, context_lines?)	Read local source text around a file:line.
mem_read(address, length?)	Read process memory at an address.
run_to_crash(program, args?, env?, cwd?, timeout?)	Run until stop/termination; returns a snapshot if it stops (e.g., crash).

Journals

Each session writes a JSONL journal to:

~/.llmdbg/sessions/<session-id>.jsonl

Override with LLMDBG_SESSION_DIR.

Smoke test

scripts/smoke.sh