agent-dbg

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