This is a submission for the GitHub Copilot CLI Challenge
What I Built
DebugHook is an attempt to add the 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. This project 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 came from a recent project where I was working with terminal agents and hit a lot of bugs. I spent a lot of time chasing issues in code that the agent had generated or run: wrong assumptions, off-by-ones, bad state—and no good way to pause and inspect. I had to pick up each bug manually, add prints, re-run, and reason from partial output. That friction is what pushed me to build something in this direction: a way to break in when the agent runs code, use the same debuggers I’d use for my own code (pdb, lldb), and step through instead of guessing from logs.
What it takes to use it (and what’s needed to build it): You need a terminal agent workflow (e.g. GitHub Copilot CLI or similar) that runs or generates code. DebugHook sits in that pipeline so that when the agent executes Python or native code, execution can be handed off to pdb or lldb instead of running to completion. On the tooling side: pdb (built into Python) or lldb (LLVM debugger) installed, and a way to intercept or wrap the agent’s execution (e.g. running the agent’s code in a subprocess or through a runner that can spawn a debugger). What I built is the direction and glue for that—the “debug mode” that was missing—so that the same workflows you use for normal development (breakpoints, step, inspect) apply when the code is coming from an agent.
Demo
https://drive.google.com/drive/folders/1_9LZHS29Ed53hkM0c327DezEYrnLz9TQ?usp=sharing
Github Repo: https://github.com/hs094/DebugHook
My Experience with GitHub Copilot CLI
What I used it for: I used GitHub Copilot CLI while building DebugHook for scaffolding, exploring how to wire pdb/lldb into an agent execution path, and for quick refactors and debugging of my own code. It helped with boilerplate (e.g. runner scripts, subprocess handling), with understanding existing debugger APIs (pdb’s programmatic use, lldb’s Python bindings), and with iterating on the “glue” between the terminal agent and the debugger.
What I learned: The main takeaway was how much faster I could move when I could describe the goal (e.g. “run this script under pdb and capture the first breakpoint”) and get a first version of the integration code, then refine it. I also learned where Copilot CLI shines—repetitive patterns, API lookup, small fixes—and where I still had to think carefully (architecture of when to hand off to the debugger, handling stdin/stdout for pdb in a subprocess). Another learning: it was useful to break the work into small, testable steps and prompt for each step, rather than asking for the whole flow at once.
Impact on the experience: Having Copilot CLI in the loop made it easier to try different ways of hooking the debugger (e.g. python -m pdb, or embedding pdb in the runner) without getting stuck on syntax or docs. When I hit bugs in my code while building DebugHook, I could describe the symptom and get suggested fixes or tests, which kept the focus on the “debug mode for agents” idea instead of on boilerplate. If I were to do it again, I’d lean on it earlier for the subprocess and TTY handling around pdb, since that was one of the trickier parts.
Top comments (0)