{"id":13574366,"url":"https://github.com/plasma-umass/ChatDBG","last_synced_at":"2025-04-04T15:30:44.941Z","repository":{"id":145137215,"uuid":"616130227","full_name":"plasma-umass/ChatDBG","owner":"plasma-umass","description":"ChatDBG - AI-assisted debugging. Uses AI to answer 'why'","archived":false,"fork":false,"pushed_at":"2024-04-30T22:59:07.000Z","size":2810,"stargazers_count":710,"open_issues_count":0,"forks_count":38,"subscribers_count":24,"default_branch":"main","last_synced_at":"2024-05-01T11:45:03.391Z","etag":null,"topics":["c-programming","cpp-programming","debugger","debugging-tools","gpt-3","lldb","pdb","python"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plasma-umass.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-19T17:39:30.000Z","updated_at":"2024-05-10T01:40:22.706Z","dependencies_parsed_at":"2024-05-10T01:40:20.289Z","dependency_job_id":"b958f8cc-8109-4def-89a0-bb47080dd195","html_url":"https://github.com/plasma-umass/ChatDBG","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2FChatDBG","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2FChatDBG/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2FChatDBG/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2FChatDBG/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plasma-umass","download_url":"https://codeload.github.com/plasma-umass/ChatDBG/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247202527,"owners_count":20900794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-programming","cpp-programming","debugger","debugging-tools","gpt-3","lldb","pdb","python"],"created_at":"2024-08-01T15:00:50.919Z","updated_at":"2025-04-04T15:30:39.932Z","avatar_url":"https://github.com/plasma-umass.png","language":"C++","funding_links":[],"categories":["Python","\u003ca name=\"programming\"\u003e\u003c/a\u003eProgramming"],"sub_categories":[],"readme":"# ChatDBG\n\nby [Emery Berger](https://emeryberger.com), [Stephen Freund](https://www.cs.williams.edu/~freund/index.html), [Kyla Levin](https://khlevin.github.io/KylaHLevin/index.html), [Nicolas van Kempen](https://nvankempen.com/) (ordered alphabetically)\n\n[![PyPI Latest Release](https://img.shields.io/pypi/v/chatdbg.svg)](https://pypi.org/project/chatdbg/)\n[![Downloads](https://static.pepy.tech/badge/chatdbg)](https://pepy.tech/project/chatdbg)\n[![Downloads](https://static.pepy.tech/badge/chatdbg/month)](https://pepy.tech/project/chatdbg)\n\nChatDBG is an AI-based debugging assistant for C/C++/Python/Rust code that integrates large language models into a standard debugger (`pdb`, `lldb`, `gdb`, and `windbg`) 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.\n\nAs far as we are aware, ChatDBG is the *first* debugger to automatically perform root cause analysis and to provide suggested fixes.\n\n**Watch ChatDBG in action!**\n| LLDB on [test-overflow.cpp](https://github.com/plasma-umass/ChatDBG/blob/main/samples/cpp/test-overflow.cpp) | GDB on [test-overflow.cpp](https://github.com/plasma-umass/ChatDBG/blob/main/samples/cpp/test-overflow.cpp)  | Pdb on [bootstrap.py](https://github.com/plasma-umass/ChatDBG/blob/main/samples/python/bootstrap.py) |\n|:-------------------------:|:-------------------------:|:-------------------------:|\n| \u003ca href=\"https://asciinema.org/a/RsAGFFmsicIvMW8xgvPP6PW2f\" target=\"_blank\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/plasma-umass/ChatDBG/main/media/lldb.svg\" /\u003e\u003c/a\u003e| \u003ca href=\"https://asciinema.org/a/bMWOyyrh7WXWsTCFboyKpqwTq\" target=\"_blank\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/plasma-umass/ChatDBG/main/media/gdb.svg\" /\u003e\u003c/a\u003e|\u003ca href=\"https://asciinema.org/a/qulxiJTqwVRJPaMZ1hcBs6Clu\" target=\"_blank\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/plasma-umass/ChatDBG/main/media/pdb.svg\" /\u003e\u003c/a\u003e|\n\nFor technical details and a complete evaluation, see our arXiv paper, [_ChatDBG: An AI-Powered Debugging Assistant_](https://arxiv.org/abs/2403.16354) ([PDF](https://github.com/plasma-umass/ChatDBG/blob/main/ChatDBG-arxiv-2403.16354.pdf)).\n\n\u003e [!NOTE]\n\u003e\n\u003e ChatDBG for `pdb`, `lldb`, and `gdb` are feature-complete; we are currently backporting features for these debuggers into the other debuggers.\n\u003e\n\n## Installation\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e ChatDBG currently needs to be connected to an [OpenAI account](https://openai.com/api/). _Your account will need to have a positive balance for this to work_ ([check your balance](https://platform.openai.com/account/usage)). 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.](https://platform.openai.com/account/api-keys)\n\u003e\n\u003e Once you have an API key, set it as an environment variable called `OPENAI_API_KEY`.\n\u003e\n\u003e ```bash\n\u003e export OPENAI_API_KEY=\u003cyour-api-key\u003e\n\u003e ```\n\nInstall ChatDBG using `pip` (you need to do this whether you are debugging Python, C, or C++ code):\n\n```bash\npython3 -m pip install chatdbg\n```\n\nIf 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.\n\n### Installing as an `lldb` extension\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cB\u003e\u003cTT\u003elldb\u003c/TT\u003e installation instructions\u003c/B\u003e\n\u003c/summary\u003e\n\nInstall ChatDBG into the `lldb` debugger by running the following command:\n\n#### Linux\n\n```bash\npython3 -m pip install ChatDBG\npython3 -c 'import chatdbg; print(f\"command script import {chatdbg.__path__[0]}/chatdbg_lldb.py\")' \u003e\u003e ~/.lldbinit\n```\n\nIf you encounter an error, you may be using an older version of LLVM. Update to the latest version as follows:\n\n```\nsudo apt install -y lsb-release wget software-properties-common gnupg\ncurl -sSf https://apt.llvm.org/llvm.sh | sudo bash -s -- 18 all\n# LLDB now available as `lldb-18`.\n```\n\n#### Mac\n\n```bash\nxcrun python3 -m pip install ChatDBG\nxcrun python3 -c 'import chatdbg; print(f\"command script import {chatdbg.__path__[0]}/chatdbg_lldb.py\")' \u003e\u003e ~/.lldbinit\n```\n\nThis will install ChatDBG as an LLVM extension.\n\u003c/details\u003e\n\n### Installing as a `gdb` extension\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cB\u003e\u003cTT\u003egdb\u003c/TT\u003e installation instructions\u003c/B\u003e\n\u003c/summary\u003e\n\nInstall ChatDBG into the `gdb` debugger by running the following command:\n\n```bash\npython3 -m pip install ChatDBG\npython3 -c 'import chatdbg; print(f\"source {chatdbg.__path__[0]}/chatdbg_gdb.py\")' \u003e\u003e ~/.gdbinit\n```\n\nThis will install ChatDBG as a GDB extension.\n\u003c/details\u003e\n\n### Installing as a `WinDBG` extension\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cB\u003e\u003cTT\u003eWinDBG\u003c/TT\u003e installation instructions\u003c/B\u003e\n\u003c/summary\u003e\n\n1. **Install WinDBG**: Follow instructions [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/) if `WinDBG` is not installed already.\n1. **Install `vcpkg`**: Follow instructions [here](https://vcpkg.io/en/getting-started) if `vcpkg` is not installed already.\n1. **Install Debugging Tools for Windows**: Install the Windows SDK [here](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) and check the box `Debugging Tools for Windows`.\n1. **Navigate to the `src\\chatdbg` directory**: `cd src\\chatdbg`\n1. **Install needed dependencies**: Run`vcpkg install`\n1. **Build the chatdbg.dll extension**: Run`mkdir build \u0026 cd build \u0026 cmake .. \u0026 cmake --build . \u0026 cd ..`\n\n**Using ChatDBG**:\n\n * Load into WinDBGX:\n   * Run `windbgx your_executable_here.exe`\n   * Click the menu items `View` -\u003e `Command browser`\n   * Type `.load debug\\chatdbg.dll`\n * After running code and hitting an exception / signal:\n   * Type `!why` in Command browser\n\u003c/details\u003e\n\n\n## Usage\n\n### Debugging Python\n\nTo use ChatDBG to debug Python programs, simply run your Python script as follows:\n\n```bash\nchatdbg -c continue yourscript.py\n```\n\nChatDBG is an extension of the standard Python debugger `pdb`. Like\n`pdb`, when your script encounters an uncaught exception, ChatDBG will\nenter post mortem debugging mode.\n\nUnlike other debuggers, you can then use the `why` command to ask\nChatDBG why your program failed and get a suggested fix.  After the LLM responds,\nyou may issue additional debugging commands or continue the conversation by entering\nany other text.\n\n#### IPython and Jupyter Support\n\nTo use ChatDBG as the default debugger for IPython or inside Jupyter Notebooks,\ncreate a IPython profile and then add the necessary exensions on startup.  (Modify\nthese lines as necessary if you already have a customized profile file.)\n\n```bash\nipython profile create\necho \"c.InteractiveShellApp.extensions = ['chatdbg.chatdbg_pdb', 'ipyflow']\" \u003e\u003e ~/.ipython/profile_default/ipython_config.py\n```\n\nOn the command line, you can then run:\n\n```bash\nipython --pdb yourscript.py\n```\n\nInside Jupyter, run your notebook with the [ipyflow kernel](https://github.com/ipyflow/ipyflow) and include this line magic at the top of the file.\n\n```\n%pdb\n```\n\n\n### Debugging native code (C, C++, or Rust with \u003cTT\u003elldb\u003c/TT\u003e / \u003cTT\u003egdb\u003c/TT\u003e)\n\nTo 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).  \n\nThe 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.\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cB\u003eDebugging Rust programs\u003c/B\u003e\n\u003c/summary\u003e\n\nTo use ChatDBG with Rust, you need to do two steps: modify your\n`Cargo.toml` file and add one line to your source program.\n\n1. Add this to your `Cargo.toml` file:\n\n```toml\n[dependencies]\nchatdbg = \"0.6.2\"\n\n[profile.dev]\npanic = \"abort\"\n\n[profile.release]\npanic = \"abort\"\n```\n\n2. In your program, apply the `#[chatdbg::main]` attribute to your `main`\nfunction:\n\n```rust\n#[chatdbg::main]\nfn main() {\n```\n\nNow you can debug your Rust code with `gdb` or `lldb`.\n\n\u003c/details\u003e\n\n### Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cB\u003eChatDBG example in \u003cTT\u003elldb\u003c/TT\u003e\u003c/B\u003e\n\u003c/summary\u003e\n\n```gdb\n(ChatDBG lldb) run\nProcess 85494 launched: '/Users/emery/git/ChatDBG/test/a.out' (arm64)\nTEST 1\nTEST -422761288\nTEST 0\nTEST 0\nTEST 0\nTEST 0\nTEST 0\nTEST 0\nProcess 85494 stopped\n* thread #1, queue = 'com.apple.main-thread', stop reason = EXC_BAD_ACCESS (code=1, address=0x100056200)\n    frame #0: 0x0000000100002f64 a.out`foo(n=8, b=1) at test.cpp:7:22\n   4     int x[] = { 1, 2, 3, 4, 5 };\n   5     \n   6     void foo(int n, float b) {\n-\u003e 7       cout \u003c\u003c \"TEST \" \u003c\u003c x[n * 10000] \u003c\u003c endl;\n   8     }\n   9     \n   10    int main()\nTarget 0: (a.out) stopped.\n```\n\nAsk `why` to have ChatDBG provide a helpful explanation why this program failed, and suggest a fix:\n\n\n```gdb\n(ChatDBG lldb) why\nThe root cause of this error is accessing an index of the array `x`\nthat is out of bounds. In `foo()`, the index is calculated as `n *\n10000`, which can be much larger than the size of the array `x` (which\nis only 5 elements). In the given trace, the program is trying to\naccess the memory address `0x100056200`, which is outside of the range\nof allocated memory for the array `x`.\n\nTo fix this error, we need to ensure that the index is within the\nbounds of the array. One way to do this is to check the value of `n`\nbefore calculating the index, and ensure that it is less than the size\nof the array divided by the size of the element. For example, we can\nmodify `foo()` as follows:\n\n    ```\n    void foo(int n, float b) {\n      if (n \u003c 0 || n \u003e= sizeof(x)/sizeof(x[0])) {\n        cout \u003c\u003c \"ERROR: Invalid index\" \u003c\u003c endl;\n        return;\n      }\n      cout \u003c\u003c \"TEST \" \u003c\u003c x[n] \u003c\u003c endl;\n    }\n    ```\n\nThis code checks if `n` is within the valid range, and prints an error\nmessage if it is not. If `n` is within the range, the function prints\nthe value of the element at index `n` of `x`. With this modification,\nthe program will avoid accessing memory outside the bounds of the\narray, and will print the expected output for valid indices.\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cB\u003eChatDBG example in Python (\u003cTT\u003epdb\u003c/TT\u003e)\u003c/B\u003e\n\u003c/summary\u003e\n\n```python\nTraceback (most recent call last):\n  File \"yourscript.py\", line 9, in \u003cmodule\u003e\n    print(tryme(100))\n  File \"yourscript.py\", line 4, in tryme\n    if x / i \u003e 2:\nZeroDivisionError: division by zero\nUncaught exception. Entering post mortem debugging\nRunning 'cont' or 'step' will restart the program\n\u003e yourscript.py(4)tryme()\n-\u003e if x / i \u003e 2:\n```\n\nAsk `why` to have ChatDBG provide a helpful explanation why this program failed, and suggest a fix:\n\n```python\n(ChatDBG Pdb) why\nThe root cause of the error is that the code is attempting to\ndivide by zero in the line \"if x / i \u003e 2\". As i ranges from 0 to 99,\nit will eventually reach the value of 0, causing a ZeroDivisionError.\n\nA possible fix for this would be to add a check for i being equal to\nzero before performing the division. This could be done by adding an\nadditional conditional statement, such as \"if i == 0: continue\", to\nskip over the iteration when i is zero. The updated code would look\nlike this:\n\ndef tryme(x):\n    count = 0\n    for i in range(100):\n        if i == 0:\n            continue\n        if x / i \u003e 2:\n            count += 1\n    return count\n\nif __name__ == '__main__':\n    print(tryme(100))\n```\n\n\u003c/details\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplasma-umass%2FChatDBG","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplasma-umass%2FChatDBG","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplasma-umass%2FChatDBG/lists"}