agent-dbg Debugger

agent-dbg is a CLI debugger that supports Node.js (V8/CDP), Bun (WebKit/JSC), 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 agent-dbg launch --brk node app.js

tsx / ts-node TypeScript agent-dbg launch --brk tsx src/app.ts

Bun JavaScript / TypeScript agent-dbg launch --brk bun app.ts

LLDB C / C++ / Rust / Swift agent-dbg launch --brk --runtime lldb ./program

The runtime is auto-detected from the launch command for JS runtimes. For native code, use --runtime lldb .

Core Debug Loop

1. Launch with breakpoint at first line

agent-dbg launch --brk node app.js

Or: agent-dbg launch --brk bun app.ts

Or: agent-dbg launch --brk --runtime lldb ./my_program

Or attach to a running process with the --inspect flag

agent-dbg attach 9229

2. Set breakpoints at suspicious locations

agent-dbg break src/handler.ts:42 agent-dbg break src/utils.ts:15 --condition "count > 10"

3. Run to breakpoint

agent-dbg continue

4. Inspect state (shows location, source, locals, stack)

agent-dbg state

5. Drill into values

agent-dbg props @v1 # expand object agent-dbg props @v1 --depth 3 # expand nested 3 levels agent-dbg eval "x + 1"

6. Fix and verify (JS/TS only)

agent-dbg set count 0 # change variable agent-dbg hotpatch src/utils.js # live-edit (reads file from disk) agent-dbg continue # verify fix

Debugging Strategies

Bug investigation -- narrow down with breakpoints

agent-dbg launch --brk node app.js agent-dbg break src/api.ts:50 # suspect line agent-dbg break src/api.ts:60 --condition "!user" # conditional agent-dbg continue agent-dbg vars # check locals agent-dbg eval "JSON.stringify(req.body)" # inspect deeply agent-dbg step over # advance one line agent-dbg state # see new state

Native code debugging (C/C++/Rust)

agent-dbg launch --brk --runtime lldb ./my_program agent-dbg break main.c:42 agent-dbg break-fn main # function breakpoint (DAP only) agent-dbg continue agent-dbg vars # inspect locals agent-dbg eval "array[i]" # evaluate expression agent-dbg step into # step into function

Attach to running/test process

Start with inspector enabled

node --inspect app.js

Or: bun --inspect app.ts

Then attach

agent-dbg attach 9229 agent-dbg state

Trace execution flow with logpoints (no pause)

agent-dbg logpoint src/auth.ts:20 "login attempt: ${username}" agent-dbg logpoint src/auth.ts:45 "auth result: ${result}" agent-dbg continue agent-dbg console # see logged output

Exception debugging

agent-dbg catch uncaught # pause on uncaught exceptions agent-dbg continue # runs until exception agent-dbg state # see where it threw agent-dbg eval "err.message" # inspect the error agent-dbg stack # full call stack

TypeScript source map support

agent-dbg automatically resolves .ts paths via source maps. Set breakpoints using .ts paths, see .ts source in output. Use --generated to see compiled .js if needed.

Ref System

Every output assigns short refs. Use them everywhere:

• @v1..@vN -- variables: agent-dbg props @v1 , agent-dbg set @v2 true

• @f0..@fN -- stack frames: agent-dbg eval --frame @f1 "this"

• BP#1..N -- breakpoints: agent-dbg break-rm BP#1 , agent-dbg break-toggle BP#1

• LP#1..N -- logpoints: agent-dbg break-rm LP#1

Refs @v /@f reset on each pause. BP# /LP# persist until removed.

Key Flags

• --json -- machine-readable JSON output on any command

• --session NAME -- target a specific session (default: "default")

• --runtime NAME -- select debug adapter (e.g. lldb for native code)

• --generated -- bypass source maps, show compiled JS (on state/source/stack)

Command Reference

See references/commands.md for full command details and options.

Tips

• agent-dbg state after stepping always shows location + source + locals -- usually enough context

• agent-dbg state -c for source only, -v for vars only, -s for stack only -- save tokens

• agent-dbg eval supports await -- useful for async inspection (JS/TS)

• agent-dbg blackbox "node_modules/**" -- skip stepping into dependencies

• agent-dbg hotpatch file reads the file from disk -- edit the file first, then hotpatch (JS/TS only)

• agent-dbg break-fn funcName -- function breakpoints work with DAP runtimes (LLDB)

• Execution commands (continue , step , pause , run-to ) auto-return status

• agent-dbg stop kills the debugged process and daemon