jdb-debugger

JDB Agentic Debugger

An AI agent plugin that teaches AI agents to debug Java applications in real time using JDB — the command-line debugger shipped with every JDK. Compatible with GitHub Copilot CLI and Claude Code.

Why an Agentic Debugger?

AI coding agents are already powerful analysts. They can read source code, decompile .class files, run javap to inspect bytecode, and reason about what should happen at runtime. They can attach jcmd, jstack, and jmap to a live JVM to grab thread dumps, heap histograms, and GC stats — all without JDWP. When something goes wrong, they can insert print statements, re-run the program, and parse the output.

So why give them JDB on top of all that?

Because none of those tools give an agent control over execution. They produce snapshots — what the JVM looks like right now or after the fact. But many bugs require an agent to pause the program at a precise moment and interrogate it: What is this variable's value on this line? Which branch did the code actually take? What did the object look like before the method mutated it? That's what a debugger does — and only a debugger.

Specifically, JDB gives an agent capabilities no other JDK or OS tool provides:

• Break on the exact moment of failure — set a breakpoint on a line, method, or exception class, and the JVM pauses right there. Not a snapshot taken sometime after — the actual instant. The agent can then inspect locals, walk the call stack, and evaluate expressions against live objects in that frozen frame.
• Step through execution line by line — follow the actual path the code takes through polymorphic dispatch, reflection, and dynamically loaded classes. No other tool lets an agent say "execute one more line and show me what changed."
• Evaluate expressions in context — print order.getItems().size() or eval config.getTimeout() * 2 against real objects on the current stack frame. This isn't heap analysis — it's interactive interrogation of live state at a precise point in execution.
• Reproduce and isolate timing-dependent bugs — a breakpoint freezes a thread mid-execution, letting an agent inspect a race condition or state corruption that no amount of thread dumps or logging can reliably capture, because those tools change timing or only show state after the fact.

Tools like jcmd and jstack tell an agent what the JVM is doing. JDB lets an agent control what happens next. That's the difference between monitoring and debugging — and it's why agents need both. JDB ships with every JDK, requires no IDE, and works over a simple text protocol, making it the ideal bridge between AI agents and live Java processes.

What This Plugin Does

When activated, this plugin enables AI agents to:

• Launch a Java application under JDB for step-by-step debugging
• Attach to a running JVM with JDWP enabled (local or remote)
• Set breakpoints at lines, methods, constructors, or on exceptions
• Step through code — step into, step over, step up
• Inspect variables — locals, fields, expressions, full object dumps
• Analyze threads — thread dumps, deadlock detection, thread switching
• Collect diagnostics — automated thread dumps and class listings
• Bulk set breakpoints from a file for repeatable debugging sessions

Quick Start

GitHub Copilot :: Claude Code CLI

# Add the marketplace
/plugin marketplace add brunoborges/jdb-agentic-debugger

# Install the plugin
/plugin install jdb-agentic-debugger@jdb-agentic-debugger

GitHub Copilot Coding Agents :: Visual Studio Code

The .agent.md files in agents/ and the skill in skills/jdb-debugger/ are compatible with GitHub Copilot coding agent. To use them:

1. Copy the agents/ files into your project's .github/agents/ folder
2. Copy the skills/jdb-debugger/ directory into your project (or reference it)
3. Open Copilot Chat and select the JDB Debugger agent from the agent picker

Agents

The plugin includes a multi-agent chain for orchestrated Java debugging workflows. The agents are defined as .agent.md files in the agents/ directory and work with both Claude Code and GitHub Copilot.

Agent Architecture

User → JDB Debugger (orchestrator)
         ├── jdb-session       → Interactive debugging (launch/attach, breakpoints, stepping)
         ├── jdb-diagnostics   → Quick JVM health checks (thread dumps, deadlock detection)
         └── jdb-analyst       → Analysis and report consolidation