Open Source · MIT License

Debugger CLI for
AI Agents

Fast, token-efficient, no fluff. Real debugging for agents — variables, stack, breakpoints — via short @ref handles.

$ bun install --global debug-that
$ npx skills add theodo-group/debug-that
GitHub npm Quick Start
dbg — debug-that
debug-that CLI demo showing launch, breakpoints, and variable inspection
Quick Start

Debug in 30 seconds

# Launch and pause at entry > dbg launch --brk tsx src/app.ts Session "default" started (pid 70445) Paused at ./src/app.ts:0:1 # Set a breakpoint > dbg break src/app.ts:19 BP#1 set at src/app.ts:19 # Run to breakpoint > dbg continue Paused at ./src/app.ts:19:21 Source: 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); 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" # Inspect deeper > dbg props @v3 name "Alice" age 30 # Evaluate expressions > dbg eval "alice.name.toUpperCase()" "ALICE"
Features

Built for machines, useful for humans

Every design decision optimizes for token efficiency and programmatic consumption. No colors, no decorations — just structured data.

@

@ref System

Every variable, frame, and breakpoint gets a short handle like @v1, @f0, BP#1. Agents reference entities without parsing complex output.

<

Token-Efficient

No ANSI colors, no box drawing. Compact one-line-per-entity output. Every byte of output is meaningful data, not decoration.

>

Multi-Runtime

Node.js, Bun, TypeScript, C/C++/Rust/Swift via LLDB. Auto-detects runtime from the launch command. One CLI for everything.

~

Daemon Architecture

Persistent background sessions with stateless CLI commands. Launch once, inspect repeatedly. Sessions survive between agent turns.

!

Hot-Patching

Live-edit running JavaScript/TypeScript code without restarting. Fix bugs mid-session. Changes take effect on next function call.

#

Source Maps

Debug TypeScript with original source locations. Breakpoints resolve to TS files. Stack traces show your code, not compiled output.

Runtimes

One debugger, every runtime

Auto-detects the runtime from your launch command and connects via the appropriate protocol adapter.

Node.js
JavaScript / TypeScript
Supported
V8 Inspector (CDP)
Bun
JavaScript / TypeScript
Supported
WebKit Inspector (JSC)
LLDB
C / C++ / Rust / Swift
Supported
Debug Adapter Protocol
Python
Python
Supported
DAP (debugpy)
Deno
JavaScript / TypeScript
Planned
Go
delve
Planned
Java
Java / Kotlin (JDWP)
Planned
Commands

30+ commands, zero ambiguity

Each command does one thing. Every error suggests the next valid command.

> dbg --help dbg — Debugger CLI for AI agents Usage: dbg <command> [options] Session: launch [--brk] <command...> Start + attach debugger [--dsym <path>] [--source-map <from>:<to>] attach <pid|ws-url|port> 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 <file>:<line> 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 <keyword>] eval <expression> 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 <path>] [--all] [--generated] search <query> Search loaded scripts [--regex] [--case-sensitive] [--file <id>] scripts [--filter <pattern>] List loaded scripts modules [--filter <pattern>] List loaded modules/libraries (DAP only) console [--since N] [--level] Console output [--clear] exceptions [--since N] Captured exceptions Breakpoints: break <file>:<line> Set breakpoint [--condition <expr>] [--hit-count <n>] [--continue] [--pattern <regex>:<line>] break-rm <BP#|all> Remove breakpoint break-ls List breakpoints break-toggle <BP#|all> Enable/disable breakpoints breakable <file>:<start>-<end> List valid breakpoint locations logpoint <file>:<line> <tpl> Set logpoint [--condition <expr>] catch [all|uncaught|caught|none] Pause on exceptions Mutation: set <@ref|name> <value> Change variable value set-return <value> Change return value (at return point) hotpatch <file> [--dry-run] Live-edit script source Blackboxing: blackbox <pattern...> Skip stepping into matching scripts blackbox-ls List current patterns blackbox-rm <pattern|all> Remove patterns Source Maps: sourcemap [file] Show source map info sourcemap --disable Disable resolution globally Setup: install <adapter> Download managed adapter binary install --list Show installed adapters Diagnostics: logs [-f|--follow] Show CDP protocol log [--limit N] [--domain <name>] [--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

Daemon + adapter pattern

Stateless CLI talks to a persistent daemon over Unix sockets. The daemon manages sessions and delegates to runtime-specific protocol adapters.

CLIstateless commands
Unix socket IPC
Daemonpersistent, per-session
DebugSessionCDP path (JavaScript)
RuntimeAdapterstrategy pattern
NodeAdapterV8 / CDP
BunAdapterJSC / WebKit
CdpClientWebSocket
V8 / JSC Inspector
DapSessionDAP path (native)
DapClientstdin / stdout
lldb-dapdebugpy, etc.