debug-that CLI

---
name: dbg
description: >
  Debug applications using the dbg CLI debugger.
  Supports Node.js (V8/CDP), Bun (WebKit/JSC), Python (debugpy/DAP), Java (JDWP/DAP), and native code via LLDB (DAP).
  Use when: (1) investigating runtime bugs by stepping through code, (2) inspecting
  variable values at specific execution points, (3) setting breakpoints and conditional
  breakpoints, (4) evaluating expressions in a paused context, (5) hot-patching code
  without restarting (JS/TS), (6) debugging test failures by attaching to a running process,
  (7) debugging C/C++/Rust/Swift with LLDB, (8) debugging Python via debugpy,
  (9) any task where understanding runtime behavior requires a debugger.
  Triggers: "debug this", "set a breakpoint", "step through", "inspect variables",
  "why is this value wrong", "trace execution", "attach debugger", "runtime error",
  "segfault", "core dump".
---

# dbg Debugger

`dbg` is a CLI debugger that supports **Node.js** (V8/CDP), **Bun** (WebKit/JSC), **Python** (via debugpy/DAP), **Java** (via JDWP/DAP) and **native code** (C/C++/Rust/Swift via LLDB/DAP). It uses short `@refs` for all entities -- use them instead of long IDs.

## Supported Runtimes

| Runtime | Language | Launch example |
|---------|----------|----------------|
| Node.js | JavaScript | `dbg launch --brk node app.js` |
| tsx / ts-node | TypeScript | `dbg launch --brk tsx src/app.ts` |
| Bun | JavaScript / TypeScript | `dbg launch --brk bun app.ts` |
| Bun executable (`bun build --compile`) | JavaScript / TypeScript | `dbg launch --brk ./my-cli --its-flags` |
| debugpy | Python | `dbg launch --brk python3 app.py` (or attach -- see Python section) |
| LLDB | C / C++ / Rust / Swift | `dbg launch --brk --runtime lldb ./program` |
| JDWP | Java | `dbg launch --brk --runtime java ./program` |

The runtime is auto-detected from the launch command for JS and Python runtimes, including executables compiled by Bun (else pass `--runtime bun`). Everything after the program's name goes to it unchanged. For native code, use `--runtime lldb`. Python can also attach to a running `debugpy` listener over TCP (`--runtime python`).

## Core Debug Loop

```bash
# 1. Launch with breakpoint at first line
dbg launch --brk node app.js
# Or: dbg launch --brk bun app.ts
# Or: dbg launch --brk python3 app.py
# Or: dbg launch --brk --runtime lldb ./my_program
# Or attach to a running process with the --inspect flag
dbg attach 9229

# 2. Set breakpoints at suspicious locations
dbg break src/handler.ts:42
dbg break src/utils.ts:15 --condition "count > 10"

# 3. Run to breakpoint (--wait blocks until it pauses or the program ends;