https://github.com/theodo-group/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.
https://github.com/theodo-group/debug-that
agent bun claude cli debugger lldb nodejs
Last synced: 2 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/theodo-group/debug-that
- Owner: theodo-group
- License: mit
- Created: 2026-02-09T14:02:12.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T09:16:02.000Z (3 months ago)
- Last Synced: 2026-03-31T11:30:49.842Z (3 months ago)
- Topics: agent, bun, claude, cli, debugger, lldb, nodejs
- Language: TypeScript
- Homepage: https://theodo-group.github.io/debug-that/
- Size: 31.4 MB
- Stars: 132
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# debug-that
Debugger CLI built for AI agents. Fast, token-efficient, no fluff.
**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.
Inspired by Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) CLI — the same `@ref` concept, applied to debugging instead of browsing.
## Supported Runtimes & Languages
| Runtime | Language | Status | Protocol |
|---------|----------|--------|----------|
| Node.js | JavaScript | Supported | V8 Inspector (CDP) |
| Node.js + tsx/ts-node | TypeScript | Supported | V8 Inspector (CDP) + Source Maps |
| Bun | JavaScript / TypeScript | Supported | WebKit Inspector (JSC) |
| LLDB | C / C++ / Rust / Swift | Supported | DAP (Debug Adapter Protocol) |
| Deno | JavaScript / TypeScript | Planned | V8 Inspector (CDP) |
| Python (debugpy) | Python | Supported | DAP |
| Go (delve) | Go | Planned | DAP |
| Java (JDWP) | Java / Kotlin | Planned | DAP |
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.
## Install
Requires [Bun](https://bun.sh).
```bash
bun install --global debug-that
npx skills add theodo-group/debug-that # Install Claude Code skill
```
## Example
```bash
> dbg launch --brk tsx src/app.ts
Session "default" started (pid 70445)
Paused at ./src/app.ts:0:1
> dbg break src/app.ts:19
BP#1 set at src/app.ts:19
> dbg continue
Paused at ./src/app.ts:19:21 (other)
Source:
16|
17|const alice: Person = { name: "Alice", age: 30 };
18|const greeting: string = greet(alice);
> 19|const sum: number = add(2, 3);
^
20|console.log(greeting);
21|console.log("Sum:", sum);
22|
Locals:
@v1 greet Function greet(person)
@v2 add Function add(a,b)
@v3 alice Object { name: "Alice", age: 30 }
@v4 greeting "Hello, Alice! Age: 30"
Stack:
@f0 (anonymous) ./src/app.ts:19:21
@f1 run node:internal/modules/esm/module_job:413:25
Breakpoints: 1 active
```
## Usage
```bash
# Node.js
dbg launch --brk node app.js
# TypeScript (via tsx)
dbg launch --brk tsx src/app.ts
# Bun
dbg launch --brk bun app.ts
# C/C++ (via LLDB)
dbg launch --brk --runtime lldb ./my_program
# Attach to a running process (any runtime with --inspect)
dbg attach 9229
# Debug loop
dbg break src/handler.ts:42
dbg continue
dbg vars
dbg props @v3
dbg eval "x + 1"
dbg step over
dbg set @v1 100
dbg hotpatch src/handler.ts # live-edit from disk (JS/TS only)
dbg stop
```
## Commands
| Category | Commands |
|---|---|
| Session | `launch`, `attach`, `stop`, `status`, `sessions` |
| Execution | `continue`, `step [over\|into\|out]`, `pause`, `run-to`, `restart-frame` |
| Inspection | `state`, `vars`, `stack`, `eval`, `props`, `source`, `scripts`, `search`, `console`, `exceptions` |
| Breakpoints | `break`, `break-rm`, `break-ls`, `break-toggle`, `breakable`, `logpoint`, `catch`, `break-fn` (DAP only) |
| Mutation | `set`, `set-return`, `hotpatch` |
| Blackbox | `blackbox`, `blackbox-ls`, `blackbox-rm` |
dbg --help full reference
```
dbg — Debugger CLI for AI agents
Usage: dbg [options]
Session:
launch [--brk] Start + attach debugger
[--dsym ] [--source-map :]
attach Attach to running process
stop Kill process + daemon
sessions [--cleanup] List active sessions
status Session info
Execution (returns state automatically):
continue Resume execution
step [over|into|out] Step one statement
run-to : Continue to location
pause Interrupt running process
restart-frame [@fN] Re-execute frame from beginning
Inspection:
state [-v|-s|-b|-c] Debug state snapshot
[--depth N] [--lines N] [--frame @fN] [--all-scopes] [--compact] [--generated]
vars [name...] Show local variables
[--frame @fN] [--all-scopes]
stack [--async-depth N] Show call stack
[--generated] [--filter ]
eval Evaluate expression
[--frame @fN] [--silent] [--timeout MS] [--side-effect-free]
props <@ref> Expand object properties
[--own] [--depth N] [--private] [--internal]
source [--lines N] Show source code
[--file ] [--all] [--generated]
search Search loaded scripts
[--regex] [--case-sensitive] [--file ]
scripts [--filter ] List loaded scripts
modules [--filter ] List loaded modules/libraries (DAP only)
console [--since N] [--level] Console output
[--clear]
exceptions [--since N] Captured exceptions
Breakpoints:
break : Set breakpoint
[--condition ] [--hit-count ] [--continue] [--pattern :]
break-rm Remove breakpoint
break-ls List breakpoints
break-toggle Enable/disable breakpoints
breakable :- List valid breakpoint locations
logpoint : Set logpoint
[--condition ]
catch [all|uncaught|caught|none] Pause on exceptions
Mutation:
set <@ref|name> Change variable value
set-return Change return value (at return point)
hotpatch [--dry-run] Live-edit script source
Blackboxing:
blackbox Skip stepping into matching scripts
blackbox-ls List current patterns
blackbox-rm Remove patterns
Source Maps:
sourcemap [file] Show source map info
sourcemap --disable Disable resolution globally
Setup:
install Download managed adapter binary
install --list Show installed adapters
Diagnostics:
logs [-f|--follow] Show CDP protocol log
[--limit N] [--domain ] [--clear]
Global flags:
--session NAME Target session (default: "default")
--json JSON output
--color ANSI colors
--help-agent LLM reference card
--help Show this help
--version Show version
```
## Architecture
```
CLI (stateless) --> Unix socket IPC --> Daemon (per session)
|
DebugSession / DapSession
/ \
CDP path (JS) DAP path (native)
| |
RuntimeAdapter DapClient
/ \ (stdin/stdout)
NodeAdapter BunAdapter |
(CDP/V8) (WebKit/JSC) lldb-dap / etc.
\ /
CdpClient (WebSocket)
|
V8/JSC Inspector
```
The daemon manages two session types:
- **DebugSession** (CDP) — for JavaScript runtimes (Node.js, Bun). Uses `RuntimeAdapter` to handle protocol differences between V8 and JSC.
- **DapSession** (DAP) — for native debuggers (LLDB, etc.). Communicates with a debug adapter over stdin/stdout using the Debug Adapter Protocol.