tapedbg

A small Rust CLI that drives a single LLDB debug session over DAP.

One debuggee at a time, attach-only, macOS. Every invocation writes exactly one JSON object to stdout and exits, so an LLM coding assistant can drive it via plain Bash tool calls with no MCP or persistent service required. A tiny auto-spawned daemon owns the codelldb child so session state survives across CLI invocations.

tapedbg (CLI)  ──unix socket──▶  tapedbgd (daemon)  ──DAP/TCP──▶  codelldb  ──▶  debuggee
  (ephemeral)                     (owns session)                   (adapter)

Prerequisites

• macOS.
• codelldb. The easy path is the VSCode extension vadimcn.vscode-lldb; its bundled adapter is discovered automatically at ~/.vscode/extensions/vadimcn.vscode-lldb-*/adapter/codelldb. Override with TAPEDBG_CODELLDB=/abs/path/to/codelldb if needed.

Install

cargo install --path crates/tapedbg
cargo install --path crates/tapedbgd

Both are required — the CLI auto-spawns tapedbgd from the same directory (or $PATH) on first use.

Quickstart

cargo build -p smoke-target --bin sleeper
./target/debug/sleeper &
tapedbg attach --pid $!
tapedbg bp crates/smoke-target/src/bin/sleeper.rs:18
tapedbg continue            # blocks until the breakpoint fires
tapedbg locals --format debug
tapedbg quit

continue and step block indefinitely — call them with Bash(..., run_in_background=true) or from a second shell, and tapedbg interrupt from elsewhere to unblock.

Useful commands

• tapedbg attach --pid N — attach to a PID.
• tapedbg status — current session state.
• tapedbg bp <file:line> / bp-list / bp-rm <id> — breakpoints.
• tapedbg continue / step over|in|out / interrupt — execution control.
• tapedbg stack [--depth N] — stack frames.
• tapedbg locals [--frame N] [--format raw|debug] — frame locals.
• tapedbg expand <var_ref> — expand a compound variable.
• tapedbg eval <expr> [--frame N] — LLDB expression evaluation (native evaluator, macros not supported).
• tapedbg quit — stop the daemon.

See tapedbg --help / tapedbg <sub> --help for the full surface and NOTES.md for design details, error codes, scripting tips, and troubleshooting.

License

MIT. See LICENSE.