ChatDBG

by Emery Berger, Stephen Freund, Kyla Levin, Nicolas van Kempen (ordered alphabetically)

Read the paper!

Watch the talk!

ChatDBG is an AI-based debugging assistant for C/C++/Python/Rust code that integrates large language models into a standard debugger (pdb, lldb, gdb) to help debug your code. With ChatDBG, you can engage in a dialog with your debugger, asking open-ended questions about your program, like why is x null?. ChatDBG will take the wheel and steer the debugger to answer your queries. ChatDBG can provide error diagnoses and suggest fixes.

As far as we are aware, ChatDBG is the first debugger to automatically perform root cause analysis and to provide suggested fixes.

Watch ChatDBG in action! | LLDB on test-overflow.cpp | GDB on test-overflow.cpp | Pdb on bootstrap.py | |:-------------------------:|:-------------------------:|:-------------------------:| | <a href="https://asciinema.org/a/RsAGFFmsicIvMW8xgvPP6PW2f" target="_blank"><img src="https://raw.githubusercontent.com/plasma-umass/ChatDBG/main/media/lldb.svg" /></a>| <a href="https://asciinema.org/a/bMWOyyrh7WXWsTCFboyKpqwTq" target="_blank"><img src="https://raw.githubusercontent.com/plasma-umass/ChatDBG/main/media/gdb.svg" /></a>|<a href="https://asciinema.org/a/qulxiJTqwVRJPaMZ1hcBs6Clu" target="_blank"><img src="https://raw.githubusercontent.com/plasma-umass/ChatDBG/main/media/pdb.svg" /></a>|

For technical details and a complete evaluation, see our FSE'25 paper, ChatDBG: An AI-Powered Debugging Assistant (PDF).

[!NOTE]

ChatDBG for pdb, lldb, and gdb are feature-complete; we are currently backporting features for these debuggers into the other debuggers.

Installation

[!IMPORTANT]

ChatDBG currently needs to be connected to an OpenAI account. Your account will need to have a positive balance for this to work (check your balance). If you have never purchased credits, you will need to purchase at least $1 in credits (if your API account was created before August 13, 2023) or $0.50 (if you have a newer API account) in order to have access to GPT-4, which ChatDBG uses. Get a key here.

Once you have an API key, set it as an environment variable called OPENAI_API_KEY.

export OPENAI_API_KEY=<your-api-key>

Install ChatDBG using pip (you need to do this whether you are debugging Python, C, or C++ code):

python3 -m pip install chatdbg

If you are using ChatDBG to debug Python programs, you are done. If you want to use ChatDBG to debug native code with gdb or lldb, follow the installation instructions below.

Installing as an lldb extension

<details> <summary> <B><TT>lldb</TT> installation instructions</B> </summary>

Install ChatDBG into the lldb debugger by running the following command:

Linux

python3 -m pip install ChatDBG
python3 -c 'import chatdbg; print(f"command script import {chatdbg.__path__[0]}/chatdbg_lldb.py")' >> ~/.lldbinit

If you encounter an error, you may be using an older version of LLVM. Update to the latest version as follows:

sudo apt install -y lsb-release wget software-properties-common gnupg
curl -sSf https://apt.llvm.org/llvm.sh | sudo bash -s -- 18 all
# LLDB now available as `lldb-18`.

Mac

xcrun python3 -m pip install ChatDBG
xcrun python3 -c 'import chatdbg; print(f"command script import {chatdbg.__path__[0]}/chatdbg_lldb.py")' >> ~/.lldbinit

This will install ChatDBG as an LLVM extension.

</details>

Installing as a gdb extension

<details> <summary> <B><TT>gdb</TT> installation instructions</B> </summary>

Prerequisites

GDB must be built with Python support. To check if your GDB has Python support and which version it uses, run:

gdb --batch -ex "python import sys; print(f'Python {sys.version}')"

If this prints a Python version (3.9 or higher required), you're good to go. If you get an error like "Python scripting is not supported", you need to install a GDB build with Python support.

Installation

Install ChatDBG and configure GDB to load it:

python3 -m pip install ChatDBG
python3 -c 'import chatdbg; print(f"source {chatdbg.__path__[0]}/chatdbg_gdb.py")' >> ~/.gdbinit

[!NOTE] The second command runs a Python script that outputs a GDB source command, which is then appended to your ~/.gdbinit file. This tells GDB to load ChatDBG on startup. After running this, your ~/.gdbinit should contain a line like:

source /path/to/site-packages/chatdbg/chatdbg_gdb.py

Verifying Installation

To verify ChatDBG is loaded correctly:

gdb --batch -ex "python import chatdbg"

If this runs without errors, ChatDBG is properly installed. When you start GDB, you should see the prompt change to (ChatDBG gdb).

Troubleshooting

"Undefined command: why": This means ChatDBG didn't load. Check that:

1. Your ~/.gdbinit contains the source line (not Python code)
2. The path in the source line points to an existing file
3. GDB's Python can import chatdbg: gdb --batch -ex "python import chatdbg"

Python version mismatch: If GDB uses a different Python than your system default, install ChatDBG using GDB's Python:

gdb --batch -ex "python import subprocess, sys; subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'ChatDBG'])"

Then regenerate the gdbinit line using the same Python.

</details>

Usage

Debugging Python

To use ChatDBG to debug Python programs, simply run your Python script as follows:

chatdbg -c continue yourscript.py

ChatDBG is an extension of the standard Python debugger pdb. Like pdb, when your script encounters an uncaught exception, ChatDBG will enter post mortem debugging mode.

Unlike other debuggers, you can then use the why command to ask ChatDBG why your program failed and get a suggested fix. After the LLM responds, you may issue additional debugging commands or continue the conversation by entering any other text.

IPython and Jupyter Support

To use ChatDBG as the default debugger for IPython or inside Jupyter Notebooks, create a IPython profile and then add the necessary exensions on startup. (Modify these lines as necessary if you already have a customized profile file.)

ipython profile create
echo "c.InteractiveShellApp.extensions = ['chatdbg.chatdbg_pdb', 'ipyflow']" >> ~/.ipython/profile_default/ipython_config.py

On the command line, you can then run:

ipython --pdb yourscript.py

Inside Jupyter, run your notebook with the ipyflow kernel and include this line magic at the top of the file.

%pdb

Debugging native code (C, C++, or Rust with <TT>lldb</TT> / <TT>gdb</TT>)

To use ChatDBG with lldb or gdb, just run native code (compiled with -g for debugging symbols) with your choice of debugger; when it crashes, ask why. This also works for post mortem debugging (when you load a core with the -c option).

The native debuggers work slightly differently than Pdb. After the debugger responds to your question, you will enter into ChatDBG's command loop, as indicated by the (ChatDBG chatting) prompt. You may continue issuing debugging commands and you may send additional messages to the LLM by starting those messages with "chat". When you are done, type quit to return to the debugger's main command loop.

<details> <summary> <B>Debugging Rust programs</B> </summary>

To use ChatDBG with Rust, you need to do two steps: modify your Cargo.toml file and add one line to your source program.

1. Add this to your Cargo.toml file:

[dependencies]
chatdbg = "0.6.2"

[profile.dev]
panic = "abort"

[profile.release]
panic = "abort"

2. In your program, apply the #[chatdbg::main] attribute to your main function:

#[chatdbg::main]
fn main() {

Now you can debug your Rust code with gdb or lldb.

</details>

Examples

<details> <summary> <B>ChatDBG example in <TT>lldb</TT></B> </summary>

(ChatDBG lldb) run
Process 85494 launched: '/Users/emery/git/ChatDBG/test/a.out' (arm64)
TEST 1
TEST -422761288
TEST 0
TEST 0
TEST 0
TEST 0
TEST 0
TEST 0
Process 85494 stopped
* thread #1, queue = 'com.apple.main-thread', stop reason = EXC_BAD_ACCESS (code=1, address=0x100056200)
    frame #0: 0x0000000100002f64 a.out`foo(n=8, b=1) at test.cpp:7:22
   4     int x[] = { 1, 2, 3, 4, 5 };
   5
   6     void foo(int n, float b) {
-> 7       cout << "TEST " << x[n * 10000] << endl;
   8     }
   9
   10    int main()
Target 0: (a.out) stopped.

Ask why to have ChatDBG provide a helpful explanation why this program failed, and suggest a fix:

(ChatDBG lldb) why
The root cause of this error is accessing an index of the array `x`
that is out of bounds.