Docs › Agent › Debug mode

Debug mode

Find the cause of a bug from what the program actually does at runtime, fix it, prove the fix, and leave no logging behind.

On this page

Some bugs only show up when the program runs: a value that is off, things happening in the wrong order, a race. Reading the code and fixing what looks wrong is a guess. Debug mode makes the agent measure first: it states what it thinks the causes might be, adds logging that tells them apart, runs the failing case (or asks you to), reads the log, and only then fixes the cause the evidence points at.

Start a debug run

  1. Open a folder: Debug, like Agent, works on files.
  2. Choose Debug in the composer's mode control, or press Cmd+. (Ctrl+.) until it shows Debug.
  3. Describe the bug: what you did, what you expected and what happened. The box suggests this with Describe the bug.

What the agent does

  1. Reproduce. It finds or writes the smallest command that shows the bug: a test, a script or a request. If only you can make it happen, in a browser, on a device or with your data, it puts the logging in first and asks you.
  2. Hypothesise. It names the three to five likeliest causes, H1, H2 and so on.
  3. Instrument. It adds three to eight temporary log lines that would tell the causes apart, each marked with a comment containing astracode-debug. Where it can start the program itself inside the editor, it uses the editor's debugger instead, with breakpoints and logpoints that need no edit.
  4. Run and read. It clears the log, reproduces the bug, and reads what was logged. It says which cause the log confirms and which it rules out, citing the lines. If none is confirmed it forms new ideas and logs again.
  5. Fix. It makes the smallest change that fixes the confirmed cause. A delay, a retry or a sleep does not count.
  6. Prove it. It marks the logging as after the fix, reproduces again, and compares the two logs.
  7. Clean up. It removes every line marked astracode-debug. A run that tries to finish with any left is sent back to remove them.

It ends by stating the cause in a sentence or two, with the log lines that showed it.

When it asks you to reproduce

If the bug needs you, a card titled Reproduce the bug lists the exact steps: what to open, what to click or type, what to look at. Follow them, then answer:

After the fix, a card titled Check the fix asks you to follow the same steps and answer Fixed or Still broken. Still broken sends it back to its hypotheses with the new log. AstraCode reads what the program logged while you followed the steps, so you do not need to copy anything.

Where the log goes

Each chat gets its own debug log. Code that can make a web request (a browser page, Node 18 or later) sends each line to a small local endpoint on 127.0.0.1; anything else appends a line to a file in your system's temporary folder. In both cases the agent reads it back itself. An Android emulator reaches the endpoint at 10.0.2.2. A physical phone or a container cannot reach it at all; there the agent logs to the program's own output and asks you for it.

The log takes up to 32 KB per line sent and 4 MB in all, and closes after two hours without use.

Using the debugger

Inside the editor, the agent can run a program under the editor's own debugger: a .js, .mjs, .cjs or .ts file run with Node, or any configuration in your launch.json. Breakpoints pause the program and show the call stack and variables; logpoints log a value without pausing. You see them in the gutter while it works. Every breakpoint it added, and any debug session it started, is removed when the run ends.

Approvals and checks

A debug run is an Agent run: edits and commands ask according to your approval setting, and the checks run before it ends.

If something goes wrong

← Plan mode What the agent can do →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference