Debugging

Agency has a built-in interactive debugger that runs right in your terminal. What makes it unusual is that it doesn't just step forward — because Agency checkpoints execution as it goes, you can also step backward, rewinding to any earlier point in the run.

Getting started

Put this in a file called test.agency:

node main() {
  const name = "world"
  const greeting = llm("Say hello to ${name}!")
  print(greeting)
}

Then launch the debugger:

agency debug test.agency

By default it runs the main node — pass --node <name> to debug a different one.

Stepping and rewinding

Once you're in, here are the moves you'll reach for most:

• Step forward — press s or the down arrow.
• Continue — press c or space to run until the next debugger statement (or the end).
• Step backward — press the up arrow to rewind one step, or press r to pull up a list of checkpoints, scroll with up/down, and jump to the line you want.

Rewinding works over a rolling window of recent checkpoints (30 by default). If you need to reach further back, bump it up with --rewind-size <n> — at the cost of a little more memory.

Overriding variables

You can rewrite a variable's value mid-run and watch how execution changes. Type:

:set name=newValue

The next time you step (s), the statement runs with the overridden value. Handy for exploring "what if this had been different?" without editing and recompiling your code.

Moving around the panels

The debugger shows several panels at once (source, variables, threads, and more):

• Cycle panels — tab and shift+tab.
• Scroll a focused panel — up/down arrows.
• Zoom — press z to blow the focused panel up to full screen (press again to restore).
• Switch threads — in the threads panel, press [ or ] to move between threads.

Debugging without running live

You don't always have to execute the program from scratch. The debugger can also load state you captured earlier:

• --trace <file> — open and inspect an existing .trace file instead of running live.
• --checkpoint <file> — start from a saved checkpoint.
• --dist-dir <dir> — import pre-compiled JS from a build directory instead of recompiling on the fly.

For the full list of options, see the debug CLI reference.