Skip to content
Back to search

debug-that

Universal debugger CLI built for AI agents. Allows Claude Code and Codex to debug much faster. Support Node (Javascript, Typescript), bun, lldb (C++/Rust), python. Fast, token-efficient, no fluff.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/theodo-group--debug-that/badge.svg)](/listings/theodo-group--debug-that)

HTML

<a href="/listings/theodo-group--debug-that"><img src="/api/listings/theodo-group--debug-that/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires [Bun](https://bun.sh).

bun install --global debug-that
npx skills add theodo-group/debug-that

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 240 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # debug-that
  2. Debugger CLI built for AI agents. Fast, token-efficient, no fluff.
  3. <p align="center">
  4. <img src="docs/demo.gif" alt="debug-that demo" />
  5. </p>
  6. **Why?** Agents waste tokens on print-debugging. A real debugger gives precise state inspection in minimal output — variables, stack, breakpoints — all via short `@ref` handles.
  7. Inspired by Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) CLI — the same `@ref` concept, applied to debugging instead of browsing.
  8. ## Supported Runtimes & Languages
  9. | Runtime | Language | Status | Protocol |
  10. |---------|----------|--------|----------|
  11. | Node.js | JavaScript | Supported | V8 Inspector (CDP) |
  12. | Node.js + tsx/ts-node | TypeScript | Supported | V8 Inspector (CDP) + Source Maps |
  13. | Bun | JavaScript / TypeScript | Supported | WebKit Inspector (JSC) |
  14. | LLDB | C / C++ / Rust / Swift | Supported | DAP (Debug Adapter Protocol) |
  15. | Deno | JavaScript / TypeScript | Planned | V8 Inspector (CDP) |
  16. | Python (debugpy) | Python | Supported | DAP |
  17. | Go (delve) | Go | Planned | DAP |
  18. | Java (JDWP) | Java / Kotlin | Planned | DAP |
  19. dbg auto-detects the runtime from the launch command and uses the appropriate protocol adapter. For native languages, use `--runtime lldb` to select the DAP adapter.
  20. ## Install
  21. Requires [Bun](https://bun.sh).
  22. ```bash
  23. bun install --global debug-that
  24. ```
  25. ```bash
  26. npx skills add theodo-group/debug-that
  27. ```
  28. ## Example
  29. ```bash
  30. > dbg launch --brk tsx src/app.ts
  31. Session "default" started (pid 70445)
  32. Paused at ./src/app.ts:0:1
  33. > dbg break src/app.ts:19
  34. BP#1 set at src/app.ts:19
  35. > dbg continue
  36. Paused at ./src/app.ts:19:21 (breakpoint)
  37. Source:
  38. 16|
  39. 17|const alice: Person = { name: "Alice", age: 30 };
  40. 18|const greeting: string = greet(alice);
  41. > 19|const sum: number = add(2, 3);
  42. ^
  43. 20|console.log(greeting);
  44. 21|console.log("Sum:", sum);
  45. 22|
  46. Locals:
  47. @v1 greet Function greet(person)
  48. @v2 add Function add(a,b)
  49. @v3 alice Object { name: "Alice", age: 30 }
  50. @v4 greeting "Hello, Alice! Age: 30"
  51. Stack:
  52. @f0 (anonymous) ./src/app.ts:19:21
  53. @f1 run node:internal/modules/esm/module_job:413:25
  54. Breakpoints: 1 active
  55. ```
  56. ## Usage
  57. ```bash
  58. # Node.js
  59. dbg launch --brk node app.js
  60. # TypeScript (via tsx)
  61. dbg launch --brk tsx src/app.ts
  62. # Bun
  63. dbg launch --brk bun app.ts
  64. # C/C++ (via LLDB)
  65. dbg launch --brk --runtime lldb ./my_program
  66. # Attach to a running process (any runtime with --inspect)
  67. dbg attach 9229
  68. # Attach to a Bun process (or a Bun-compiled binary) started with BUN_INSPECT.
  69. # `?break=1` holds the process until dbg attaches, then pauses on its first statement.
  70. BUN_INSPECT='ws://localhost:6499/app?break=1' ./my-bun-binary
  71. dbg attach ws://localhost:6499/app
  72. # Debug loop
  73. dbg break src/handler.ts:42
  74. dbg continue
  75. dbg vars
  76. dbg props @v3
  77. dbg eval "x + 1"
  78. dbg step over
  79. dbg set @v1 100
  80. dbg hotpatch src/handler.ts # live-edit from disk (JS/TS only)
  81. dbg stop
  82. ```
  83. ## Commands
  84. | Category | Commands |
  85. |---|---|
  86. | Session | `launch`, `attach`, `stop`, `status`, `sessions` |
  87. | Execution | `continue`, `step [over\|into\|out]`, `pause`, `run-to`, `restart-frame` |
  88. | Inspection | `state`, `vars`, `stack`, `eval`, `props`, `source`, `scripts`, `search`, `console`, `exceptions` |
  89. | Breakpoints | `break`, `break-rm`, `break-ls`, `break-toggle`, `breakable`, `logpoint`, `catch`, `break-fn` |
  90. | Mutation | `set`, `set-return`, `hotpatch` |
  91. | Blackbox | `blackbox`, `blackbox-ls`, `blackbox-rm` |
  92. <details>
  93. <summary><code>dbg --help</code> full reference</summary>
  94. ```
  95. dbg — Debugger CLI for AI agents
  96. Usage: dbg <command> [options]
  97. Session:
  98. launch [--brk] <command...> Start + attach debugger
  99. [--dsym <path>] [--source-map <from>:<to>]
  100. attach <pid|ws-url|port> Attach to running process
  101. stop Kill process + daemon
  102. sessions [--cleanup] List active sessions
  103. status Session info
  104. Execution (returns state automatically):
  105. continue [--wait <seconds>] Resume execution; --wait blocks until the next pause or exit
  106. step [over|into|out] Step one statement
  107. run-to <file>:<line> Continue to location
  108. pause Interrupt running process
  109. restart-frame [@fN] Re-execute frame from beginning
  110. Inspection:
  111. state [-v|-s|-b|-c] Debug state snapshot
  112. [--depth N] [--lines N] [--frame @fN] [--all-scopes] [--compact] [--generated]
  113. vars [name...] Show local variables
  114. [--frame @fN] [--all-scopes]
  115. stack [--async-depth N] Show call stack
  116. [--generated] [--filter <keyword>]
  117. eval <expression> Evaluate expression
  118. [--frame @fN] [--silent] [--timeout SECONDS] [--side-effect-free]
  119. props <@ref> Expand object properties
  120. [--own] [--depth N] [--private] [--internal]
  121. source [--lines N] Show source code
  122. [--file <path>] [--all] [--generated]
  123. search <query> Search loaded scripts
  124. [--regex] [--case-sensitive] [--file <id>]
  125. scripts [--filter <pattern>] List loaded scripts
  126. modules [--filter <pattern>] List loaded modules/libraries (DAP only)
  127. console [--since N] [--level] Console output
  128. [--clear]
  129. exceptions [--since N] Captured exceptions
  130. Breakpoints:
  131. break <file>:<line> Set breakpoint
  132. [--condition <expr>] [--hit-count <n>] [--continue] [--pattern <regex>:<line>]
  133. break-rm <BP#|all> Remove breakpoint
  134. break-ls List breakpoints
  135. break-toggle <BP#|all> Enable/disable breakpoints
  136. breakable <file>:<line>[-<end>] List valid breakpoint locations
  137. logpoint <file>:<line> <args> Set logpoint (console.log's arguments, e.g. '"x =", x')
  138. [--condition <expr>]
  139. catch [all|uncaught|caught|none|exit] Pause on exceptions, or as the program exits
  140. Mutation:
  141. set <@ref|name> <value> Change variable value
  142. set-return <value> Change return value (at return point)
  143. hotpatch <file> [--dry-run] Live-edit script source
  144. Blackboxing:
  145. blackbox <pattern...> Skip stepping into matching scripts
  146. blackbox-ls List current patterns
  147. blackbox-rm <pattern|all> Remove patterns
  148. Source Maps:
  149. sourcemap [file] Show source map info
  150. sourcemap <script> --pretty Show the script formatted; positions and breakpoints translate
  151. sourcemap <script> --map <file> Pair the script with a map file, re-read as it changes
  152. sourcemap --disable Disable resolution globally
  153. Setup:
  154. install <adapter> Download managed adapter binary
  155. install --list Show installed adapters
  156. Diagnostics:
  157. logs [-f|--follow] Show CDP protocol log
  158. [--limit N] [--domain <name>] [--clear]
  159. Global flags:
  160. --session NAME Target session (default: "default")
  161. --json JSON output
  162. --color ANSI colors
  163. --help-agent LLM reference card
  164. --help Show this help
  165. --version Show version
  166. ```
  167. </details>
  168. ## What dbg puts in the debugged process
  169. Nothing, for most of a session: breakpoints, stepping and inspection go through the inspector protocol. Three features evaluate code in the process, and say so in their output:
  170. - `catch exit` installs a `process.on("exit")` listener that pauses as the program exits. Bun gets it on every connection, because Bun drops inspector messages still queued when it exits, and the pause flushes them: without it, the last lines a program logs before exiting never reach `dbg console`.
  171. - `break-fn` on a native function (`JSON.parse`) wraps it in place, since the engine cannot pause inside a native. The wrapper is removed with the breakpoint or when dbg disconnects; `break-ls` notes it.
  172. - Logpoints on Bun route their values through a no-op function on `globalThis`, so that they never print into the program's own output.
  173. ## Architecture
  174. ```
  175. CLI (stateless) --> Unix socket IPC --> Daemon (per session)
  176. |
  177. DebugSession / DapSession
  178. / \
  179. CDP path (JS) DAP path (native)
  180. | |
  181. RuntimeAdapter DapClient
  182. / \ (stdin/stdout)
  183. NodeAdapter BunAdapter |
  184. (CDP/V8) (WebKit/JSC) lldb-dap / etc.
  185. \ /
  186. CdpClient (WebSocket)
  187. |
  188. V8/JSC Inspector
  189. ```
  190. The daemon manages two session types:
  191. - **DebugSession** (CDP) — for JavaScript runtimes (Node.js, Bun). Uses `RuntimeAdapter` to handle protocol differences between V8 and JSC.
  192. - **DapSession** (DAP) — for native debuggers (LLDB, etc.). Communicates with a debug adapter over stdin/stdout using the Debug Adapter Protocol.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.