ChatDBG: a debugger extension that answers why, by driving your debugger from a language model

The mechanism is a debugger you argue with, not a chatbot about code

ChatDBG integrates into `pdb`, `lldb` and `gdb` rather than sitting beside them. Once loaded, you ask open-ended questions in the debugger's own prompt, phrased the way you would ask a colleague, such as why is x null. The tool then takes the wheel and steers the debugger to work out an answer, which the README describes as automatic root cause analysis with suggested fixes.

That framing matters, because it is the difference between a tool that reads your source and one that inspects runtime state. A language model given a file can guess where a bug probably is. A language model driving a debugger can check.

For Python the integration is the least involved, because ChatDBG extends `pdb` directly. Like `pdb`, it enters post mortem debugging mode when your script hits an uncaught exception, and unlike `pdb` you can then ask why rather than stepping yourself.

The authors are Emery Berger, Stephen Freund, Kyla Levin and Nicolas van Kempen, listed alphabetically in the README, from UMass Amherst's PLASMA group. The academic framing shows in the artefacts: `ChatDBG.pdf` sits in the repository root as the FSE'25 paper, and the README points to it for technical details and the evaluation. If you want to know how well the root cause analysis performs, the paper is where the answer is, not the README.

Installation is one pip command plus an OpenAI key with credit

The base install is deliberately narrow:

python3 -m pip install chatdbg

That one command covers Python, C and C++ debugging, as the README states. Native debugging then needs the debugger wired to load the extension.

For `lldb` on Linux, ChatDBG appends an import line to your `~/.lldbinit`:

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

For `gdb`, the equivalent writes a `source` line into `~/.gdbinit` instead, and GDB must be built with Python support, 3.9 or higher. You can check that before installing anything:

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

The credit requirement is stated more firmly than most projects state it. The README has an IMPORTANT callout: ChatDBG needs an OpenAI account, your account needs a positive balance, and you need to buy at least $1 in credits if the API account predates August 13, 2023, or $0.50 for a newer one, in order to have GPT-4 access. That is a real barrier for anyone evaluating this offline, and it is better to know before installing than after your first question.

Once you have a key, the README has you export it as `OPENAI_API_KEY`.

Running it, and reading the prompt change

Debugging a Python script means passing `-c continue`, which tells ChatDBG to run to the crash before engaging:

chatdbg -c continue yourscript.py

The verification step is small and worth doing, because a debugger extension that silently fails to load looks exactly like a debugger that ignored your question. The README's own check for GDB is:

gdb --batch -ex "python import chatdbg"

If that runs clean, the prompt changes to `(ChatDBG gdb)`. The README also documents the failure mode you will hit otherwise: an undefined command error for `why` means ChatDBG did not load, and there are three things to check, that `~/.gdbinit` contains the `source` line rather than Python code, that the path in that line points at a file that exists, and that GDB's Python can import the package.

That third point leads to the subtler variant of the problem, a Python version mismatch between GDB's interpreter and your system default. The README's fix is to install through GDB's own Python and then regenerate the init line with that same interpreter:

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

For context on the maintenance state: the README notes that ChatDBG for `pdb`, `lldb` and `gdb` is feature-complete and that features are currently being backported from those into the other debuggers.

Rust is claimed in the description but not in the install guide

This is the clearest gap between what the project says and what it documents.

The README opens by describing ChatDBG as an assistant for C, C++, Python and Rust code, and the repository backs the Rust claim with real directories: `rust-support/` at the top level and `samples/rust/` alongside `samples/python/` and `samples/cpp/`. The GitHub topics list includes `rust` too.

What the install section does not contain is a Rust integration. The three documented integrations are `pdb`, `lldb` and `gdb`. `rust-support/` exists but the README gives no command for it, no debugger it attaches to, and no requirement.

So the Rust support appears to be partial or experimental, and the documentation does not say which. If Rust is your target language, treat this as something to verify directly in the `rust-support/` directory rather than something the install guide will set up for you. The same applies to the note about backporting features into other debuggers: it implies a broader debugger surface exists beyond the three documented ones, which is another reason the Rust path may work without being documented.

Two smaller inconsistencies to keep in mind. The README says to install with `python3 -m pip install chatdbg` in lowercase, while the project name in `pyproject.toml` is `ChatDBG`, and the lldb and gdb instructions use the capitalized form. PyPI normalizes the two, so both work. And the same instructions require Python 3.11 or higher in `pyproject.toml`, a stricter floor than the 3.9 or higher the README asks you to check for inside GDB.

How it compares to a breakpoint, a stack trace and other AI debugging tools

The fair baseline is not another AI tool. It is the ten minutes you would otherwise spend writing a conditional breakpoint.

A debugger already lets you stop when a condition holds. What it does not let you do is express the condition in the language you would use to describe the bug. ChatDBG's contribution is the translation from prose to debugger navigation: you say why is x null, and it inspects frames, values and call context to build an answer. If your reasoning is already precise enough to write as `break` plus a condition, you lose nothing by staying with `pdb`.

Against `pdb`'s own post mortem mode, the difference is that ChatDBG does the navigation. You do not step through twelve frames to find which one nulled your object. The README is explicit that this is the point, framing the project as the first debugger to automatically perform root cause analysis and suggest fixes, with the caveat that this is a claim the authors make as far as they are aware.

The dependency picture is worth weighing before you install. `pyproject.toml` pins `litellm==1.55.9` with an exact version and no range, alongside `openai`, `rich`, `ipdb`, `ipython`, `numpy`, `PyYAML`, `traitlets` and `llm-utils`. An exact pin on the model-provider shim in a debugging tool that already wants to reach a paid API is a plausible source of dependency conflicts in an existing virtual environment.

It is also worth naming what this project is not. It is not a test generator, not a code reviewer, and not a static analyzer. It is a debugging aid for the moment you are already stopped in a debugger, which is a narrow and genuinely hard problem, and one an academic group with a published evaluation is well placed to have measured properly.

Editorial conclusion

ChatDBG is worth trying when you are already at the point of writing a long conditional breakpoint by hand, since that is exactly the work it automates, and when your stack is Python, C or C++ on pdb, lldb or gdb. It is the wrong tool if your failures are not reproducible in a debugger, and the wrong tool for Rust despite the language appearing in the description, because no Rust integration is documented in the install section. Two things to know before adopting it in a team workflow. It requires an OpenAI account with a positive balance, and `litellm` is pinned to exactly 1.55.9, which will collide with anything else in your environment holding a different version. Versions v1.0.0 and v1.0.1 arrived in 2025 with the last push on 2026-07-20. Start with `chatdbg -c continue yourscript.py` against one of the sample programs under `samples/`.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. plasma-umass/ChatDBG on GitHub
4. README
5. Releases