Agent Debugger

A debugger for AI agents. Set breakpoints, inspect state, evaluate expressions, test fixes in-place. Attach to running servers by PID — no restart, no code changes, no manual setup.

Philosophy

The debugger is a scalpel, not a flashlight. You don't turn it on to look around. You turn it on to make one precise cut — confirm or kill a specific hypothesis about why the program is broken. If you're "exploring" in the debugger, you've already lost.

Every session starts before the debugger. Read the code. Read the traceback. Form a theory. Know exactly what breakpoint you'll set and what eval you'll run before you type a single command. The debugger is the experiment, not the investigation.

eval is the only command that matters. vars, step, stack, source — these are all setup. The eval is the actual experiment. It's where you test your hypothesis against reality. Everything else is scaffolding to get you to the right eval at the right moment.

Half of all bugs don't need a debugger. Read the traceback. Read the code. Check the types. Grep for the error message. Look at git blame. Most bugs surrender to careful reading. Reach for the debugger only when the bug depends on runtime state you can't determine statically.

The Rules

1. Read first, debug second. Never start a debug session without reading the relevant code and forming a hypothesis. The debugger confirms theories — it doesn't generate them.

2. One breakpoint, one question. Each breakpoint should answer a specific question. "Is x a string here?" "Is balance negative after this call?" "Does this branch execute?" If you can't articulate the question, you're not ready to debug.