Universal debugger CLI built for AI agents with @ref handle system and token-efficient output, supporting Node.js, Bun, LLDB, Python and more.
debug-that is a universal debugger CLI developed by Theodo Group, designed for AI agents. Its core goal is to give AI coding assistants like Claude Code and Codex real debugging capabilities while minimizing token consumption.
The project uses a Daemon + stateless CLI architecture: a persistent background process manages debug sessions, while the CLI communicates via Unix socket, keeping sessions alive across multiple Agent conversation turns. Every variable, stack frame, and breakpoint is assigned a short handle (e.g., @v1, @f0, BP#1), allowing Agents to reference entities precisely without parsing complex output. Output format strips ANSI colors and decorative borders, renders one entity per line, and supports --json mode for programmatic consumption.
The underlying implementation uses a dual-protocol path: the CDP path adapts differences between Node.js (V8 Inspector) and Bun (WebKit Inspector) via the Strategy pattern; the DAP path communicates with debug adapters like lldb-dap and debugpy via stdin/stdout, covering C/C++/Rust/Swift and Python. Runtime is auto-detected from launch commands or can be manually specified.
Capabilities include hot-patching (JS/TS via inspector API live replacement, Java via ECJ compilation + JDI redefineClasses), Source Map breakpoint positioning, conditional/logpoint/exception breakpoints, blackbox script skipping, and attaching to running processes. The command system includes 30+ commands covering session management, execution control, state inspection, breakpoint management, and variable modification.
Requires Bun as runtime dependency. Installable via bun install --global or as a Claude Code / Codex skill. Primarily written in TypeScript (92%) with Java (8%) for hot-patch compilation. Current version v0.6.2, MIT licensed.
Multi-Runtime Support Status
| Runtime | Languages | Protocol | Status |
|---|---|---|---|
| Node.js | JS / TS | CDP (V8 Inspector) + Source Maps | ✅ Supported |
| Bun | JS / TS | WebKit Inspector (JSC) | ✅ Supported |
| LLDB | C / C++ / Rust / Swift | DAP | ✅ Supported |
| Python | Python | DAP (debugpy) | ✅ Supported (maturity TBD) |
| Java | Java | JDWP/DAP + ECJ Hotpatch | 🔶 Partial (v0.6.0 hotpatch) |
| Deno | JS / TS | CDP | 📋 Planned |
| Go | Go | delve/DAP | 📋 Planned |
Command Overview
| 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 |
| Modification | set, set-return, hotpatch |
| Blackbox | blackbox, blackbox-ls, blackbox-rm |
Unconfirmed Items
- npm package publish status: docs site has link but GitHub Packages shows none published
- Docs site version lag: shows v0.2.1 while repo is at v0.6.2
- Python (debugpy) support maturity lower than Node/Bun/LLDB
- Deno / Go / full Java debugging have no clear timeline
- Windows compatibility unmentioned (architecture relies on Unix socket IPC)