waxdbg

Stateless commands

waxdbg has no REPL or persistent shell. Each command does one thing, prints its result, and exits. Session commands keep their small amount of working state in a .waxdbg/ directory.

Results are JSON. A command with a result document prints exactly one of them on standard output, named by a protocol field such as wxdbg.context.v1. Add --text for the human rendering where one exists; a command without one refuses --text with a bad_usage error. A failure replaces the document with {"protocol":"wxdbg.error.v1","error":{"code":...,"message":...}}. bad_usage, no_session and internal_error are universal codes; the rest are per command and listed by waxdbg help <command>. Warnings raised while a document was built ride along in its warnings array, and print to standard error under --text or where the answer is a bare recording-analysis payload with no room for them.

Every waxdbg command is also available through wax debug. The direct form is shorter when an investigation uses many commands.

Live inspection

A live session can set conditional breakpoints, run or continue a program, step into or over statements, inspect the stack and locals, watch fields for changes, and log mutations. It can run a local native program or attach to a WebAssembly target in the browser.

Start with the shipped warehouse example in an empty directory:

wax new warehouse --example warehouse
cd warehouse
wax debug init
waxdbg break add Src/App.wax:29
waxdbg run
waxdbg step

The run pauses at the route decision; stepping enters IsBlocked at frame 3 with x = 3 and y = 1. The stack contains IsBlocked, MoveTowardDelivery, and Update.

run already answers with everything the stop knows: one wxdbg.context.v1 document holding the location, the call stack, the innermost frame's locals, the armed breakpoints, and a window of source around the stop line (--around N, 5 lines by default; 0 leaves the window out). Every command that stops the program prints that same document, and waxdbg context re-reads it without moving anything -- against an attached browser target too, where the page answers in that same vocabulary and one round trip carries the whole stop.

context is also how you ask for more of that stop, so there is no separate command to learn: --frame N reads a caller frame's locals instead of the innermost, and --object @ID (repeatable, with --depth N) renders those objects into the same document.

waxdbg context --frame 1

Choose frame indexes from the returned stack. For an object-bearing program, pass an object identity from its output to context --object @ID --depth 2; identities belong to that run, so do not copy one from an unrelated example.

Step out of IsBlocked, advance one statement, then let the run finish:

waxdbg out
waxdbg next
waxdbg break clear --all
waxdbg continue

Wax native code is the default where the local JIT is supported. Use waxdbg run --backend c for the portable generated C path. It uses WX_C_COMPILER, then CC, then clang from PATH.

Recordings

A .wxs file contains a completed Wax execution. Recording commands inspect it without requiring a live process. They report metadata and frames, render heap state, compare frame transitions, track allocations and object timelines, read API-channel outputs, find field mutations, evaluate predicates, and run typed Wax queries across recorded frames.

In the warehouse project above, make an eight-frame recording:

waxdbg recording create run.wxs --frames 8
waxdbg recording info run.wxs
waxdbg recording diff run.wxs --range 0:7

The diff includes the battery changing from 96 after frame 0 to 68 after frame 7. For recording timeline --object @ID, choose a stableId returned by this recording's diff or heap inspection and write it as @ followed by its hexadecimal value. Use the channel example below to inspect API outputs.

For typed values, range scans, and reusable analysis programs, read Queries and investigations.

The record and replay guide explains what the debugger runs when it creates a recording, how to supply channel values, how snapshots differ, and how to replay changed source with the old inputs.

Automate a channel driven recording

recording create can stage typed channel values before selected frames, so a repeatable run driven by the debugger does not need a custom host. Create the SimulationDemo files and save the schedule below as SimulationDemo/inputs.json. Ask the bound project for its exact input schema, write one JSON schedule, and pass that file into the recording:

cd SimulationDemo
wax debug init
waxdbg recording input-schema > input-schema.json
waxdbg recording create run.wxs --frames 120 --inputs inputs.json

The schedule separates complete initial values from later sparse changes. Every later change names its frame explicitly; array position is never used as the frame selector.

{
  "channelInitialValues": {
    "Simulation": { "timeScale": 1.0 }
  },
  "frameInputs": [
    {
      "frameId": 12,
      "values": {
        "Simulation": { "timeScale": 0.5 }
      }
    }
  ]
}

The schema uses the same typed JSON vocabulary as query arguments and results. It reports required initial members, nullable and optional channels, event batches, secret values, atomic text operations, and structural value types. The complete SimulationDemo example includes the manifest, source, and expected output for this schedule.

Open the Inspector

The desktop Inspector is the shortest path from a saved recording to its source, timeline, stack, and values. Initialize the project once, open the recording, then stop the background GUI server when you are finished.

cd MyProject
wax debug init
waxdbg gui run.wxs
waxdbg gui stop

Start in Timeline, choose a frame, and then use Debug and Explorer to connect that moment to program state and source. The terminal prints the local Inspector URL and the command that stops its session. Reloading the page or reopening that URL reconnects to the same local session while it is running.

Command discovery

The command set comes from the debugger registry. capabilities lists command spellings, availability, result document names, text-rendering support, and error codes. Read help <command> for its operands, options, and result schema. Options include rules such as integer bounds and required companion options, so a tool can validate a command before running it. waxdbg answers an invalid command line with bad_usage whether or not a session is bound.

waxdbg help recording diff
waxdbg help recording input-schema
waxdbg capabilities

The website publishes the canonical transport neutral debugger command registry used to generate command surfaces. It is not the target specific wxdbg.capabilities.v1 response returned by capabilities. Recording tools can use the exact recording JSON contract instead of inferring shapes from examples.

For a recording investigation performed by an agent, use the raw Inspector investigation prompt.