debug-that CLI
The dbg debugger CLI for AI agents: breakpoints, steps and variables through short @ref handles instead of print debugging
- 159 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Launches your programs and evaluates expressions inside the process, changes variables and swaps code with `hotpatch`
- A background daemon keeps the session open and listens on a Unix socket until `dbg stop` is called
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/debug-thatDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Launches your programs and evaluates expressions inside the process, changes variables and swaps code with `hotpatch`
- A background daemon keeps the session open and listens on a Unix socket until `dbg stop` is called
This is third-party code. Review the repository files before installing.
What it does
debug-that installs the `dbg` command line program that an agent uses to debug code in a live process. Instead of adding `print` calls and reading long logs, the agent launches the program under the debugger with `dbg launch --brk`, sets breakpoints with `dbg break`, steps through and reads locals, the stack and console output. Entities get short handles such as `@v1`, `@f0` and `BP#1`, so responses take few tokens. For JavaScript and TypeScript it uses the V8 Inspector in Node.js and the WebKit Inspector in Bun, for C, C++, Rust and Swift it attaches LLDB over DAP, and for Python debugpy. `dbg attach` hooks into an already running process. Commands cover expression evaluation, changing a variable, conditional breakpoints, logpoints, blackboxing libraries and `hotpatch` to edit a script from disk without a restart. The CLI is stateless: a background daemon holds the session and commands talk to it over a Unix socket. The package ships a `debug-that` skill that teaches the agent this loop.
Who it is for. Developers on Node.js, Bun, Python and native languages whose agent burns tokens on print debugging and guesses about variable values.
Good fit when
- A test fails and the variable value at the moment of the error is unclear, so the agent sets a breakpoint and reads `dbg vars`
- A Node.js server already runs with `--inspect`, and the agent attaches by port with `dbg attach 9229`
- A C++ or Rust program crashes in native code and the stack is read through LLDB
- You want to try a function fix in a live process: `dbg hotpatch` swaps the code from a file without a restart
- Logs bloat the agent's context while you need three values at one spot: `dbg logpoint` helps
Not a fit when
- Debugging happens in a browser or an environment where processes and sockets are off limits
- The language is not on the supported list: the author still marks Deno and Go as planned
- A unit test catches the bug more simply than stepping through a live program
Example request
Launch src/app.ts under dbg, set a breakpoint on line 19, run to it and show the locals and the stackLimitations
- Installing the package needs Bun.
- A few features execute code inside the debugged process: `catch exit` installs an exit handler, `break-fn` wraps a native function, and logpoints on Bun call a no-op function on `globalThis`. The command output says so.
- The README marks Java as planned, though the skill text mentions launching through JDWP, so test Java on your own project.
- `hotpatch` edits JavaScript and TypeScript only.
How to disable. End sessions with `dbg stop` and remove the package, for example `bun remove --global debug-that`. Delete the `debug-that` folder from the agent's skills directory to drop the skill. Sessions left running keep a background daemon; `dbg sessions` lists them and `dbg sessions --cleanup` clears them.
FAQ
How do I install debug-that for Claude Code?
Install the debugger with `bun install --global debug-that` (Bun is required) and add the skill with `npx skills add theodo-group/debug-that`. The agent then launches programs through `dbg launch --brk`.
How do I debug TypeScript?
Launch the program with `dbg launch --brk tsx src/app.ts`. The debugger reads source maps and shows TypeScript lines, not the compiled code.
How do I attach to a process that is already running?
Use `dbg attach` with a pid, a port or a ws address. A Node.js process must start with the `--inspect` flag and a Bun process with the `BUN_INSPECT` variable.
Which languages does debug-that support?
JavaScript and TypeScript on Node.js and Bun, Python through debugpy, and C, C++, Rust and Swift through LLDB. The README still marks Deno, Go and Java as planned.
Why is a debugger cheaper for an agent than console output?
The debugger returns variables, the stack and breakpoints as short `@v1` and `@f0` handles without editing code or reading long logs. Responses are short, so they use few tokens.
Discussion
No questions or reviews yet.
Related
CLI toolsAn MCP server for the Node.js debugger: breakpoints, stepping, variable inspection and expression evaluation at a pause
Nietzschian Debugger is a question-based debugging CLI with per-run model selection; the next invocation has its own setting.
A debugging skill built on hypotheses: the agent adds logs, reproduces the bug itself, tests its guesses and cleans up
A VS Code extension with an MCP server: an agent sets breakpoints, starts debugging from your launch.json and evaluates expressions in any language
The official Microsoft MCP server for debugging: a VS Code extension and a CLI give an agent breakpoints, steps, variables and expression evaluation
A CLI turns Git changes into a guided code walkthrough with questions and explanations written by your existing agent
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| debug-that (this card) | no | 159 | ||
| DebugMCP | yes | not required | 579 | Microsoft's official MCP server with a VS Code extension, connected through MCP |
| Node.js Debugger MCP | no | not required | 350 | an MCP debugger for Node.js only, without Bun, Python and LLDB |
README in short
The README explains the idea (agents waste tokens on print debugging), lists supported runtimes in a table and shows a sample session with responses. Next come launch examples, a table of commands by category, the full help output, a note on what the debugger puts into the process and an architecture diagram.
README badge
Original SKILL.md
--- 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;