# pi-gdb

A [Pi](https://pi.dev) extension wrapping GDB in an agent-friendly interface.
Why? Trying to automate programming can run into issues, but automated debugging
seems like a much clearer win. To install it, just rust `pi install pi-gdb`. So,
if you're writing anything compiling to native code (C, C++, Rust, Zig, ...),
here's a bunch of reasons to try it:

- **Works well with local models.** Just like Pi itself, this extension 
engineered with a minimal token footprint in mind. Even Qwen 3.6 27B at IQ3_XXS
managed to root cause some real bugs I ran into while working on my toy kernel,
and you can run that with MTP on any 16GB GPU. If you have an 8 GB GPU, Qwen 3.6
35B A3B Q4_K_M with non-shared experts offloaded to the CPU should be nearly as
good.
- **Robust error handling.** This extension parses GDB output, uses short
timeouts between individual commands, aborts the current batch of commands in
case one of them returns an error, handles unexpected process termination
correctly, and adds information about this to responses, which helps the LLM
stay on the right track. It'd be also possible to add automated command fixing
or smart symbol searches in the future.
- **Unopinionated.** The extension includes just a single `gdb` tool with a
minimal description. I recommend adding some project-local skills describing how
to attach GDB to the test suite, where to find core dumps, or recond-and-replay
recordings. With local models it can help to instruct them to start debugging
straight away rather than read files, and restart gdb and set an earlier
breakpoint if they get stuck, but YMMV. Find out what works well for your
project, and enjoy a little less time spent staring at register dumps and
assembly listings.