Content
# 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:**
```bash
sudo apt install liblldb-dev lldb
```
**macOS:**
```bash
xcode-select --install
```
**Windows:**
```powershell
winget install LLVM.LLVM
```
Note: The winget package requires Python 3.10 at runtime (see [Windows Setup](#windows-setup) below).
## Build
**Linux/macOS:**
```bash
cmake --preset default
cmake --build --preset default
```
**Windows:**
```cmd
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](https://github.com/0xeb/fastmcpp) (vendored as a submodule
under `external/fastmcpp`), which provides the MCP server, cpp-httplib and nlohmann_json.
## Usage
```bash
# 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
| Command | Description |
|---------|-------------|
| `agent help` | Show help |
| `agent version` | Show version |
| `agent mcp [bind_addr]` | Start the MCP (SSE) server, block until Ctrl+C |
| `agent http [bind_addr]` | Start the plain HTTP server, block until Ctrl+C |
`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:
```json
{
"mcpServers": {
"lldb-agent": {
"url": "http://127.0.0.1:<port>/sse"
}
}
}
```
## HTTP API
`agent http` exposes:
| Method | Path | Purpose |
|--------|------|---------|
| POST | `/exec` | Run a debugger command: `{"command": "bt"}` → `{"output": "...", "success": true}` |
| GET | `/status` | Server readiness |
| POST | `/shutdown` | Stop the server |
```bash
curl -X POST http://127.0.0.1:<port>/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:
```powershell
# 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:
```cmd
cd lldb_agent
test_lldb.cmd
```
### Quick Test
```cmd
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](https://github.com/0xeb))
Pair-programmed with Claude Code and Codex.
## License
MIT
