debug-that 0.2.1 → 0.4.0

package/README.md

@@ -2,6 +2,10 @@
 
 Debugger CLI built for AI agents. Fast, token-efficient, no fluff.
 
+<p align="center">
+  <img src="docs/demo.gif" alt="debug-that demo" />
+</p>
+
 **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.
@@ -15,7 +19,7 @@ Inspired by Vercel's [agent-browser](https://github.com/vercel-labs/agent-browse
 | 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 | Planned | DAP |
+| Python (debugpy) | Python | Supported | DAP |
 | Go (delve) | Go | Planned | DAP |
 | Java (JDWP) | Java / Kotlin | Planned | DAP |
 
@@ -106,7 +110,93 @@ dbg stop
 | Mutation | `set`, `set-return`, `hotpatch` |
 | Blackbox | `blackbox`, `blackbox-ls`, `blackbox-rm` |
 
-Run `dbg --help` or `dbg --help-agent` for the full reference.
+<details>
+<summary><code>dbg --help</code> full reference</summary>
+
+```
+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
+```
+
+</details>
 
 ## Architecture