LLDB Agent

An LLDB plugin that exposes the debugger over MCP (Model Context Protocol) and plain HTTP, so an external AI agent (Claude Code, Claude Desktop, etc.) can drive your debug session through a single dbg_exec tool.

The plugin embeds no AI. It is a thin bridge: it runs LLDB commands on request and returns their output. Bring your own agent.

Requirements

• LLDB 16+ with development headers
• CMake 3.20+
• C++17 compiler

Platform-specific requirements

Linux:

sudo apt install liblldb-dev lldb

macOS:

xcode-select --install

Windows:

winget install LLVM.LLVM

Note: The winget package requires Python 3.10 at runtime (see Windows Setup below).

Build

Linux/macOS:

cmake --preset default
cmake --build --preset default

Windows:

cmake --preset windows
cmake --build --preset windows

Output:

• Linux: build/lldb_agent.so
• macOS: build/lldb_agent.dylib
• Windows: build-windows/Release/lldb_agent.dll

The plugin depends on fastmcpp (vendored as a submodule under external/fastmcpp), which provides the MCP server, cpp-httplib and nlohmann_json.

Usage

# Start LLDB with your program
lldb ./myprogram

# Load the plugin
(lldb) plugin load /path/to/lldb_agent.so

# Start the MCP (SSE) server - blocks until Ctrl+C
(lldb) agent mcp

# ...or a plain HTTP server
(lldb) agent http

When a server starts it prints its URL and endpoints (and copies them to the clipboard on Windows). Point your MCP client at the SSE endpoint, or POST commands to the HTTP endpoint, and press Ctrl+C in LLDB to stop the server.

Commands

bind_addr defaults to 127.0.0.1 (localhost only). Pass 0.0.0.0 to listen on all interfaces — note the server has no authentication, so only do this on trusted networks.

MCP client configuration

agent mcp prints a ready-to-paste snippet, e.g. for Claude Desktop:

{
  "mcpServers": {
    "lldb-agent": {
      "url": "http://127.0.0.1:/sse"
    }
  }
}

HTTP API

agent http exposes:

curl -X POST http://127.0.0.1:/exec \
  -H "Content-Type: application/json" \
  -d '{"command": "bt"}'

Windows Setup

The LLVM package from winget requires Python 3.10 to run LLDB. Download and extract to the project bin folder:

# Download and extract embedded Python 3.10 to project bin folder
Invoke-WebRequest -Uri "https://www.python.org/ftp/python/3.10.11/python-3.10.11-embed-amd64.zip" -OutFile "$env:TEMP\python310.zip"
Expand-Archive -Path "$env:TEMP\python310.zip" -DestinationPath "..\bin\python310" -Force

Then use the test_lldb.cmd wrapper script which sets up the environment:

cd lldb_agent
test_lldb.cmd

Quick Test

test_lldb.cmd
(lldb) target create "C:\Windows\System32\notepad.exe"
(lldb) run

Press Ctrl+C to break, then start a server:

(lldb) agent mcp

Author

Elias Bachaalany (@0xeb)

Pair-programmed with Claude Code and Codex.

License

MIT