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
- Start a debug run
- What the agent does
- When it asks you to reproduce
- Where the log goes
- Using the debugger
- Approvals and checks
- If something goes wrong
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
- Open a folder: Debug, like Agent, works on files.
- Choose Debug in the composer's mode control, or press Cmd+. (Ctrl+.) until it shows Debug.
- Describe the bug: what you did, what you expected and what happened. The box suggests this with Describe the bug.
What the agent does
- 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.
- Hypothesise. It names the three to five likeliest causes, H1, H2 and so on.
- 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. - 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.
- Fix. It makes the smallest change that fixes the confirmed cause. A delay, a retry or a sleep does not count.
- Prove it. It marks the logging as after the fix, reproduces again, and compares the two logs.
- 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:
- Done: it happened, or Done: it did not happen this time.
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
- Nothing was logged: the instrumented code did not run, or could not reach the log. Make sure the steps go through the code the agent instrumented.
- Leftover log lines: search the project for
astracode-debug. Every temporary line carries it. - More on Agent run problems.
← Plan mode What the agent can do →
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems