DebugHook: A New Take at Debugging using AI Agents

Source: Dev.to

Overview

DebugHook is an attempt to add a missing debug mode to terminal agents. When agents run or generate code in the terminal, there’s usually no way to step through execution or inspect state—you’re left with logs, print statements, or replaying the same command and hoping to spot the bug. DebugHook hooks tools like pdb (Python) and lldb (native/LLVM) into that flow so you can set breakpoints, step through, and inspect variables in agent‑executed code, bringing traditional debugging to the terminal‑agent workflow.

The idea originated from a project where I was working with terminal agents and encountered many bugs in code generated or run by the agent: wrong assumptions, off‑by‑ones, bad state, and no good way to pause and inspect. I had to manually add prints, re‑run, and reason from partial output. This friction motivated the creation of a “debug mode” that lets the same debuggers I use for my own code (pdb, lldb) intervene when an agent runs code.

How It Works

1. Agent workflow integration – DebugHook sits in the pipeline of a terminal agent (e.g., GitHub Copilot CLI) that runs or generates code.
2. Execution interception – When the agent executes Python or native code, DebugHook intercepts the call and hands execution off to the appropriate debugger instead of letting it run to completion.
3. Debugger hand‑off – The tool launches pdb (built into Python) or lldb (LLVM debugger) in a subprocess, allowing you to set breakpoints, step, and inspect variables just as you would in a normal development session.

Requirements

• A terminal agent workflow that runs or generates code (e.g., GitHub Copilot CLI).
• Debuggers installed: pdb (included with Python) and/or lldb (LLVM debugger).
• Ability to intercept or wrap the agent’s execution, typically by running the agent’s code in a subprocess or through a custom runner that can spawn a debugger.

Usage Example

# Example: run a Python script generated by an agent under pdb
debughook run python my_generated_script.py --debugger pdb

# Example: run a compiled binary under lldb
debughook run ./my_generated_binary --debugger lldb

These commands illustrate how DebugHook can be invoked to start the appropriate debugger automatically.

What I Used It For

I used GitHub Copilot CLI while building DebugHook for:

• Scaffolding the project structure.
• Exploring how to wire pdb/lldb into an agent execution path.
• Quick refactors and debugging of my own code.

The process helped with boilerplate (e.g., runner scripts, subprocess handling), understanding debugger APIs (programmatic use of pdb, Python bindings for lldb), and iterating on the “glue” between the terminal agent and the debugger.

Lessons Learned

• Speed of iteration – Describing a goal (e.g., “run this script under pdb and capture the first breakpoint”) to Copilot CLI produced a first version of integration code quickly, which could then be refined.
• Strengths of Copilot CLI – Repetitive patterns, API lookup, and small fixes are well‑supported.
• Challenges – Deciding when to hand off to the debugger and handling stdin/stdout for pdb in a subprocess required careful thought.
• Incremental prompting – Breaking the work into small, testable steps and prompting for each step was more effective than asking for the entire flow at once.

Impact on the Development Experience

Having Copilot CLI in the loop made it easier to experiment with different ways of hooking the debugger (e.g., python -m pdb vs. embedding pdb in the runner) without getting stuck on syntax or documentation. When bugs arose while building DebugHook, I could describe the symptom and receive suggested fixes or tests, keeping the focus on the “debug mode for agents” idea rather than boilerplate concerns. In hindsight, I would rely on Copilot earlier for handling subprocess and TTY interactions around pdb, as those proved to be the trickier parts.

Resources

• DebugHook assets (Google Drive)