
jdb-agentic-debugger
Debug Java applications in real time using JDB. Launch JVMs under JDB, attach to running processes, set breakpoints, step through code, inspect variables, analyze threads, and diagnose exceptions.
- version
- 1.0.0
- GitHub stars
- 69
Install
/plugin install jdb-agentic-debugger@jdb-agentic-debuggerRun it inside Claude Code after adding the marketplace with /plugin marketplace add brunoborges/jdb-agentic-debugger.
Contents
Discovered from sourceSkills 2
Java Debugger (JDB) Skill
Debug Java applications interactively using the JDK's built-in command-line debugger.
Critical Rules for Agents
- NEVER create files in the workspace (no
bp.txt,cmds.txt, wrapper scripts, etc.). Use the inline CLI flags (--bp,--cmd,--auto-inspect,--timeout) provided by the skill scripts. - ALWAYS use the skill scripts in
scripts/. Never write custom JDB wrapper scripts, FIFO-based launchers, or shell scripts to drive JDB. - Compile first, then debug. Ensure classes are compiled before launching JDB.
- On Windows, invoke scripts via WSL:
wsl bash scripts/<script>.sh
Platform Support
Windows (WSL Required)
The scripts in this skill are Bash scripts. On Windows, invoke them via WSL:
wsl bash scripts/jdb-launch.sh com.example.MyApp --sourcepath src/main/java
If your compiled classes are on the Windows filesystem, WSL accesses them via /mnt/c/:
wsl bash scripts/jdb-launch.sh com.example.MyApp --classpath /mnt/c/Users/you/project/out
Ensure JDK is installed in WSL:
# Ubuntu/Debian WSL
sudo apt update && sudo apt install -y default-jdk
# Verify
which jdb && jdb -version
Linux / macOS
Scripts run natively. Ensure JDK is installed and jdb is on PATH:
export PATH=$JAVA_HOME/bin:$PATH
Decision Tree
User wants to debug Java app →
├─ App is already running with JDWP agent?
│ ├─ Yes → Attach: scripts/jdb-attach.sh --port <port>
│ └─ No → Can you restart with JDWP?
│ ├─ Yes → Launch with: scripts/jdb-launch.sh <mainclass> [args]
│ └─ No → Suggest adding JDWP agent to JVM flags (see below)
│
├─ What does the user need?
│ ├─ Set breakpoints & step through code → Interactive JDB session
│ ├─ Collect thread dumps / diagnostics → scripts/jdb-diagnostics.sh
│ └─ Catch a specific exception → Use `catch` command in JDB
│
└─ Done debugging → Detach cleanly with `quit` or Ctrl+C
Quick Start
Option 1: Launch a new JVM under JDB
bash scripts/jdb-launch.sh com.example.MyApp --sourcepath src/main/java
Option 2: Attach to a running JVM
First, ensure the target JVM was started with the JDWP agent:
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar myapp.jar
Then attach:
bash scripts/jdb-attach.sh --host localhost --port 5005
Option 3: Quick diagnostics (thread dump + deadlock detection)
bash scripts/jdb-diagnostics.sh --port 5005
Enabling JDWP on a Running Application
If the target JVM was not started with JDWP, suggest the user restart with:
# For direct Java launch
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -cp myapp.jar com.example.Main
# For Maven Spring Boot
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
# For Gradle
./gradlew bootRun --jvmArgs="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
# As environment variable
export JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
Interactive JDB Session Guide
Once inside a JDB session (launched or attached), use these commands interactively:
Setting Breakpoints
stop at com.example.MyClass:42 # Break at line 42
stop in com.example.MyClass.myMethod # Break at method entry
stop in com.example.MyClass.<init> # Break at constructor
stop in com.example.MyClass.<clinit> # Break at static initializer
For overloaded methods, specify parameter types:
stop in com.example.MyClass.process(int,java.lang.String)
Running and Stepping
run # Start the application (if launched, not attached)
cont # Continue execution after hitting a breakpoint
step # Step into the next line (enters method calls)
next # Step over to the next line (skips method internals)
step up # Run until the current method returns
Inspecting State
locals # Show all local variables in the current frame
print myVariable # Print value of a variable or expression
print myObj.getX() # Evaluate a method call
dump myObject # Show all fields of an object
eval 2 + 2 # Evaluate an arbitrary expression
Navigating the Call Stack
where # Show the current thread's call stack
where all # Show call stacks for all threads
up # Move up one frame in the stack
down # Move down one frame in the stack
up 3 # Move up 3 frames
Thread Management
threads # List all threads and their states
thread main # Switch to the "main" thread
thread 0x1a3 # Switch to thread by ID
suspend 0x1a3 # Suspend a specific thread
resume 0x1a3 # Resume a specific thread
Exception Handling
catch java.lang.NullPointerException # Break on NPE
catch java.lang.Exception # Break on any Exception
catch all # Break on all throwables
ignore java.lang.NullPointerException # Stop catching NPE
Inspecting Classes and Methods
classes # List all loaded classes
class com.example.MyClass # Show details of a class
methods com.example.MyClass # List all methods of a class
fields com.example.MyClass # List all fields of a class
Managing Breakpoints
clear # List all breakpoints
clear com.example.MyClass:42 # Remove breakpoint at line 42
clear com.example.MyClass.myMethod # Remove method breakpoint
Source Code
list # List source around current line
list 50 # List source around line 50
use /path/to/sources # Set source path
sourcepath # Show current source path
classpath # Show current classpath
Exiting
quit # Exit JDB (detaches from JVM)
exit # Same as quit
Debugging Workflow Patterns
Pattern 1: Investigate a NullPointerException (automated batch mode)
Use inline --bp flags and --auto-inspect — no files needed:
bash scripts/jdb-breakpoints.sh \
--mainclass com.example.MyClass \
--bp "catch java.lang.NullPointerException" \
--bp "stop at com.example.MyClass:42" \
--bp "stop in com.example.MyClass.processMessage" \
--auto-inspect 20
The --auto-inspect 20 flag automatically generates run + 20 cycles of
where, locals, cont + quit. The output contains the full JDB session
including stack traces, local variables, and exception details — ready for analysis.
For applications that may hang or deadlock, add --timeout <seconds> to kill the
JDB session after the specified time:
bash scripts/jdb-breakpoints.sh \
--mainclass com.example.MyClass \
--bp "catch java.lang.NullPointerException" \
--auto-inspect 10 --timeout 60
For custom commands, use --cmd flags instead of --auto-inspect:
bash scripts/jdb-breakpoints.sh \
--mainclass com.example.MyClass \
--bp "catch java.lang.NullPointerException" \
--cmd "run" --cmd "where" --cmd "locals" --cmd "print myVar" --cmd "cont" \
--cmd "where" --cmd "locals" --cmd "cont" --cmd "quit"
Pattern 2: Watch a method's behavior
# 1. Set breakpoint at method entry
stop in com.example.Service.processOrder
# 2. Continue until breakpoint is hit
cont
# 3. Inspect arguments and step through
locals
next
print result
next
print result
Pattern 3: Diagnose a deadlock
# 1. List all threads
threads
# 2. Check each blocked thread's stack
where all
# 3. Look for threads in MONITOR state holding different locks
thread <blocked-thread-id>
where
Pattern 4: Inspect values at a specific line
# 1. Set breakpoint
stop at com.example.DataProcessor:128
# 2. Continue to breakpoint
cont
# 3. Inspect everything
locals
print config.getTimeout()
dump dataMap
Important Notes
- NEVER create files in the workspace. Use inline
--bp,--cmd,--auto-inspect, and--timeoutflags. The scripts handle all temp files internally in/tmp/and clean up after themselves. - Use
--timeoutfor potentially hanging apps. Apps that deadlock or loop indefinitely will block JDB forever. Add--timeout 60(or appropriate value) so the session is automatically killed. The output will include aTIMEOUT:marker when triggered. - Compile with
-gfor full debug info. Without it,localswill show "Local variable information not available". Always compile with:javac -g -d out src/main/java/com/example/MyClass.java - JDB is line-oriented: Send one command at a time and read the output before the next command.
- Source path: Use
-sourcepathorusecommand solistcan show source code. - Classpath: Ensure compiled classes are accessible for expression evaluation.
- Thread context: Many commands operate on the "current thread". Use
threadto switch. - Suspend mode: When attaching with
suspend=y, the JVM pauses until JDB connects. Usesuspend=nfor non-blocking attachment. - Expression evaluation:
printandevalcan call methods on live objects — use with caution in production. - Batch timing: The batch mode uses configurable delays. Override via env vars:
JDB_BP_DELAY(default: 2s),JDB_RUN_DELAY(3s),JDB_CMD_DELAY(0.5s),JDB_CONT_DELAY(1s).
Reference Files
- JDB Command Reference - Complete alphabetical command reference
- JDWP Options Reference - All JDWP agent configuration options
Java Debugger (JDB) Skill
Debug Java applications interactively using the JDK's built-in command-line debugger.
Critical Rules for Agents
- NEVER create debugger helper files in the workspace (no
bp.txt,cmds.txt, wrapper scripts, etc.). Requested report artifacts such asfindings-*.mdandDEBUG-REPORT.mdare allowed. Use the inline CLI flags (--bp,--cmd,--auto-inspect,--timeout) provided by the skill scripts. - ALWAYS use the skill scripts in
scripts/. Never write custom JDB wrapper scripts, FIFO-based launchers, or shell scripts to drive JDB. - Compile first, then debug. Ensure classes are compiled before launching JDB.
- On Windows, invoke scripts via WSL:
wsl bash scripts/<script>.sh
Platform Support
Windows (WSL Required)
The scripts in this skill are Bash scripts. On Windows, invoke them via WSL:
wsl bash scripts/jdb-launch.sh com.example.MyApp --sourcepath src/main/java
If your compiled classes are on the Windows filesystem, WSL accesses them via /mnt/c/:
wsl bash scripts/jdb-launch.sh com.example.MyApp --classpath /mnt/c/Users/you/project/out
Ensure JDK is installed in WSL:
# Ubuntu/Debian WSL
sudo apt update && sudo apt install -y default-jdk
# Verify
which jdb && jdb -version
Linux / macOS
Scripts run natively. Ensure JDK is installed and jdb is on PATH:
export PATH=$JAVA_HOME/bin:$PATH
Decision Tree
User wants to debug Java app →
├─ App is already running with JDWP agent?
│ ├─ Yes → Attach: scripts/jdb-attach.sh --port <port>
│ └─ No → Can you restart with JDWP?
│ ├─ Yes → Launch with: scripts/jdb-launch.sh <mainclass> [args]
│ └─ No → Suggest adding JDWP agent to JVM flags (see below)
│
├─ What does the user need?
│ ├─ Set breakpoints & step through code → Interactive JDB session
│ ├─ Collect thread dumps / diagnostics → scripts/jdb-diagnostics.sh
│ └─ Catch a specific exception → Use `catch` command in JDB
│
└─ Done debugging → Detach cleanly with `quit` or Ctrl+C
Quick Start
Option 1: Launch a new JVM under JDB
bash scripts/jdb-launch.sh com.example.MyApp --sourcepath src/main/java
Option 2: Attach to a running JVM
First, ensure the target JVM was started with the JDWP agent:
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar myapp.jar
Then attach:
bash scripts/jdb-attach.sh --host localhost --port 5005
Option 3: Quick diagnostics (thread dump + deadlock detection)
bash scripts/jdb-diagnostics.sh --port 5005
Enabling JDWP on a Running Application
If the target JVM was not started with JDWP, suggest the user restart with:
# For direct Java launch
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -cp myapp.jar com.example.Main
# For Maven Spring Boot
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
# For Gradle
./gradlew bootRun --jvmArgs="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
# As environment variable
export JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
Interactive JDB Session Guide
Once inside a JDB session (launched or attached), use these commands interactively:
Setting Breakpoints
stop at com.example.MyClass:42 # Break at line 42
stop in com.example.MyClass.myMethod # Break at method entry
stop in com.example.MyClass.<init> # Break at constructor
stop in com.example.MyClass.<clinit> # Break at static initializer
For overloaded methods, specify parameter types:
stop in com.example.MyClass.process(int,java.lang.String)
Running and Stepping
run # Start the application (if launched, not attached)
cont # Continue execution after hitting a breakpoint
step # Step into the next line (enters method calls)
next # Step over to the next line (skips method internals)
step up # Run until the current method returns
Inspecting State
locals # Show all local variables in the current frame
print myVariable # Print value of a variable or expression
print myObj.getX() # Evaluate a method call
dump myObject # Show all fields of an object
eval 2 + 2 # Evaluate an arbitrary expression
Navigating the Call Stack
where # Show the current thread's call stack
where all # Show call stacks for all threads
up # Move up one frame in the stack
down # Move down one frame in the stack
up 3 # Move up 3 frames
Thread Management
threads # List all threads and their states
thread main # Switch to the "main" thread
thread 0x1a3 # Switch to thread by ID
suspend 0x1a3 # Suspend a specific thread
resume 0x1a3 # Resume a specific thread
Exception Handling
catch java.lang.NullPointerException # Break on NPE
catch java.lang.Exception # Break on any Exception
catch all # Break on all throwables
ignore java.lang.NullPointerException # Stop catching NPE
Inspecting Classes and Methods
classes # List all loaded classes
class com.example.MyClass # Show details of a class
methods com.example.MyClass # List all methods of a class
fields com.example.MyClass # List all fields of a class
Managing Breakpoints
clear # List all breakpoints
clear com.example.MyClass:42 # Remove breakpoint at line 42
clear com.example.MyClass.myMethod # Remove method breakpoint
Source Code
list # List source around current line
list 50 # List source around line 50
use /path/to/sources # Set source path
sourcepath # Show current source path
classpath # Show current classpath
Exiting
quit # Exit JDB (detaches from JVM)
exit # Same as quit
Debugging Workflow Patterns
Pattern 1: Investigate a NullPointerException (automated batch mode)
Use inline --bp flags and --auto-inspect — no files needed:
bash scripts/jdb-breakpoints.sh \
--mainclass com.example.MyClass \
--bp "catch java.lang.NullPointerException" \
--bp "stop at com.example.MyClass:42" \
--bp "stop in com.example.MyClass.processMessage" \
--auto-inspect 20
The --auto-inspect 20 flag automatically generates run + 20 cycles of
where, locals, cont + quit. The output contains the full JDB session
including stack traces, local variables, and exception details — ready for analysis.
For applications that may hang or deadlock, add --timeout <seconds> to kill the
JDB session after the specified time:
bash scripts/jdb-breakpoints.sh \
--mainclass com.example.MyClass \
--bp "catch java.lang.NullPointerException" \
--auto-inspect 10 --timeout 60
For custom commands, use --cmd flags instead of --auto-inspect:
bash scripts/jdb-breakpoints.sh \
--mainclass com.example.MyClass \
--bp "catch java.lang.NullPointerException" \
--cmd "run" --cmd "where" --cmd "locals" --cmd "print myVar" --cmd "cont" \
--cmd "where" --cmd "locals" --cmd "cont" --cmd "quit"
Pattern 2: Watch a method's behavior
# 1. Set breakpoint at method entry
stop in com.example.Service.processOrder
# 2. Continue until breakpoint is hit
cont
# 3. Inspect arguments and step through
locals
next
print result
next
print result
Pattern 3: Diagnose a deadlock
# 1. List all threads
threads
# 2. Check each blocked thread's stack
where all
# 3. Look for threads in MONITOR state holding different locks
thread <blocked-thread-id>
where
Pattern 4: Inspect values at a specific line
# 1. Set breakpoint
stop at com.example.DataProcessor:128
# 2. Continue to breakpoint
cont
# 3. Inspect everything
locals
print config.getTimeout()
dump dataMap
Important Notes
- NEVER create debugger helper files in the workspace. Requested report
artifacts are allowed. Use inline
--bp,--cmd,--auto-inspect, and--timeoutflags. The scripts handle temporary input internally and clean up. - Use
--timeoutfor potentially hanging apps. Apps that deadlock or loop indefinitely will block JDB forever. Add--timeout 60(or appropriate value) so the session is automatically killed. The output will include aTIMEOUT:marker when triggered. - Compile with
-gfor full debug info. Without it,localswill show "Local variable information not available". Always compile with:javac -g -d out src/main/java/com/example/MyClass.java - JDB is line-oriented: Send one command at a time and read the output before the next command.
- Source path: Use
-sourcepathorusecommand solistcan show source code. - Classpath: Ensure compiled classes are accessible for expression evaluation.
- Thread context: Many commands operate on the "current thread". Use
threadto switch. - Suspend mode: When attaching with
suspend=y, the JVM pauses until JDB connects. Usesuspend=nfor non-blocking attachment. - Expression evaluation:
printandevalcan call methods on live objects — use with caution in production. - Remote/production safety: obtain authorization before attaching, prefer a loopback or tunneled JDWP endpoint, avoid broad exception catchpoints on busy services, and treat evaluated methods as potentially state-changing.
- Batch timing: The batch mode uses configurable delays. Override via env vars:
JDB_BP_DELAY(default: 2s),JDB_RUN_DELAY(3s),JDB_CMD_DELAY(0.5s),JDB_CONT_DELAY(1s).
Reference Files
- JDB Command Reference - Complete alphabetical command reference
- JDWP Options Reference - All JDWP agent configuration options
Agents 4
You are a Java debugging analyst. You interpret stack traces, thread dumps, and diagnostic output to identify root causes. You do not run commands — you read, analyze, and write reports.
Workflow
- Read the input — stack trace, thread dump, log snippet, diagnostic file, or findings text from sub-agents
- Cross-reference when permitted — search source only when it is available and the request allows source access; otherwise use runtime evidence exclusively
- Identify the root cause:
- For exceptions: trace the null/bad value back to its origin
- For deadlocks: identify the lock acquisition order conflict
- For performance: identify threads stuck in I/O, locks, or loops
- Provide a clear report:
- What happened (symptom)
- Why it happened (root cause)
- Where in the code (file + line)
- How to fix it (concrete suggestion)
- Evidence and confidence
- Limitations or missing data
Analysis Patterns
NullPointerException
- Find the line that threw the NPE
- Trace backwards to find where the null value was assigned or passed
- Check for missing null guards, uninitialized fields, or incorrect return values
Deadlock
- Identify threads in BLOCKED state
- Map lock ownership: which thread holds which monitor
- Find the circular dependency in lock acquisition order
OutOfMemoryError
- Look for unbounded collections or caches
- Check for resource leaks (unclosed streams, connections)
- Identify hot allocation sites from the stack trace
ConcurrentModificationException
- Find the collection being modified during iteration
- Identify which threads are accessing the collection
- Suggest synchronization or concurrent collection alternatives
Writing Reports
When asked to consolidate findings into a report (e.g., DEBUG-REPORT.md):
- Read all
findings-*.mdfiles in the working directory — these are written byjdb-sessionsub-agents - Consolidate all findings into a single
DEBUG-REPORT.md - Also use any findings provided directly in your prompt text as supplementary input
- You MUST write the
DEBUG-REPORT.mdfile — do not just return text
Constraints
- DO NOT run terminal commands — you do not execute programs
- DO NOT modify source code — only analyze and recommend
- ONLY provide analysis based on evidence from the trace and source code
- When source is unavailable, do not search for it or invent file/line details; explicitly mark unavailable information
- ALWAYS write the report file when asked to consolidate findings
- If more data is needed, tell the user exactly what to collect and suggest re-invoking the JDB Debugger orchestrator
You are the JDB Debugger orchestrator. Your job is to triage Java debugging requests and delegate to the right specialist.
Timing
You MUST track accurate session timing:
- Before dispatching sub-agents, instruct the first sub-agent to run
date -u +"%Y-%m-%dT%H:%M:%SZ"as its very first command and include the output in its response asSESSION_START_TIME: <timestamp>. - After all sub-agents complete, note the timestamp from the last sub-agent's final command output. Instruct each sub-agent to run
date -u +"%Y-%m-%dT%H:%M:%SZ"as its very last command and include it in its response asSESSION_END_TIME: <timestamp>. - Use the earliest
SESSION_START_TIMEand the latestSESSION_END_TIMEacross all sub-agents to calculate the total duration. - Include both timestamps and the calculated duration in the
DEBUG-REPORT.mdtiming header.
Skill Scripts
All JDB operations MUST use the scripts from the jdb-debugger skill:
| Script | Purpose |
|---|---|
jdb-launch.sh | Launch a new JVM under JDB |
jdb-attach.sh | Attach JDB to a running JVM with JDWP |
jdb-breakpoints.sh | Launch/attach JDB with pre-loaded breakpoints |
jdb-diagnostics.sh | Collect thread dumps, deadlock info, and class listings |
On Windows, all scripts must be invoked via WSL: wsl bash scripts/<script>.sh
Report Contract
Every findings file and final report uses the same evidence contract:
- target class/process and launch or attachment mode
- start time, end time, and elapsed duration
- for each finding: symptom, runtime evidence, method/line when available, root cause, confidence, and suggested fix
- limitations, missing evidence, timeouts, and failed targets
Reports and findings are requested output artifacts and may be written in the workspace. Debugger command files, wrapper scripts, and other helper files may not.
Parallel Debugging Strategy
When the request involves multiple independent applications to debug (e.g., a list of classes to investigate), you MUST parallelize the work:
- Identify independent targets — each main class or application that can be debugged independently
- Dispatch one sub-agent per target in parallel — hand off each application to a separate
jdb-sessionagent simultaneously, not sequentially - Each sub-agent works independently — runs the app, launches JDB, sets breakpoints, inspects variables, and reports its findings for that single application
- Collect and consolidate — once all sub-agents complete, hand off all findings to
jdb-analystto produce the unified report
How to Parallelize
When you detect multiple targets (e.g., "debug AppA, AppB, AppC"):
- Launch all sub-agent handoffs at the same time — do NOT wait for one to finish before starting the next
- Each sub-agent prompt must include:
- The specific class to debug (only one per sub-agent)
- The classpath and run command for that class
- Instructions to write findings to
findings-<ClassName>.md(e.g.,findings-WarningAppTest.md) - Instructions to run
date -u +"%Y-%m-%dT%H:%M:%SZ"as its first and last terminal command, and include the outputs asSESSION_START_TIME: <timestamp>andSESSION_END_TIME: <timestamp>in the findings file - All constraints (no source access, use skill scripts, no javap)
Handling Potentially Hanging Applications
Some applications may deadlock or loop forever (e.g., threading bugs, visibility issues). When dispatching sub-agents:
- Always instruct sub-agents to use
--timeout 60withjdb-breakpoints.shto prevent indefinite hangs - Always instruct sub-agents to use
timeout 10when running apps normally (e.g.,timeout 10 java -cp classes ThreadTest) - If a sub-agent reports a timeout, that is evidence of a bug (deadlock, infinite loop, or visibility issue) — include it in the analysis
Important: Data Flow Between Agents — File-Based Reporting
Sub-agents write their findings to files — not just text responses. This is critical because background agents' text responses cannot be read back by the orchestrator.
Each jdb-session sub-agent writes a findings-<ClassName>.md file when it finishes debugging its assigned application. The orchestrator then:
- Dispatches all sub-agents in background (in parallel)
- Does NOT re-dispatch sub-agents synchronously — never duplicate work
- Waits, then checks for
findings-*.mdfiles in the working directory using thereadtool - Once all expected findings files exist, hands off to
jdb-analystto consolidate them intoDEBUG-REPORT.md
If some findings files are missing after a reasonable wait, check again — do NOT re-dispatch the sub-agent. Only if a findings file never appears should you note that sub-agent as failed.
If jdb-analyst fails to write the report, the orchestrator MUST read the findings-*.md files and write DEBUG-REPORT.md itself.
Example Parallel Dispatch
For a request to debug 5 applications, dispatch 5 sub-agents simultaneously:
- Sub-agent 1 →
jdb-session: "Debug WarningAppTest. Write findings tofindings-WarningAppTest.md." - Sub-agent 2 →
jdb-session: "Debug ConsoleAppTest. Write findings tofindings-ConsoleAppTest.md." - Sub-agent 3 →
jdb-session: "Debug AliasingCorruptionTest. Write findings tofindings-AliasingCorruptionTest.md." - ...and so on
Then: jdb-analyst → "Read all findings-*.md files in the working directory and consolidate into a single DEBUG-REPORT.md file."
Decision Tree
- Multiple independent apps to debug → dispatch parallel
jdb-sessionsub-agents (one per app), thenjdb-analystto consolidate - Single app: step through code, set breakpoints, catch exceptions, or inspect variables → hand off to
jdb-session - User wants a thread dump, deadlock check, or quick JVM health snapshot → hand off to
jdb-diagnostics - User has a stack trace, log, or diagnostic output to interpret → hand off to
jdb-analyst
Before Handing Off
- Ask clarifying questions if the intent is ambiguous
- Determine if the target JVM is already running with JDWP or needs to be launched
- Identify the main class, port, or host if known
- Tell the sub-agent which script(s) to use based on the scenario
- Pass all gathered context (class names, ports, paths) to the sub-agent
Constraints
- DO NOT run terminal commands — you only triage and delegate
- DO NOT attempt debugging yourself — always hand off to a specialist
- ONLY gather context (read files, search code) before delegating
- ALWAYS instruct sub-agents to use the skill scripts — never raw jdb commands
- DO NOT let sub-agents access or search for
.javasource files - For source-free requests, require runtime evidence and never infer source details that JDB did not expose
- Before remote or production attachment, confirm authorization and warn that breakpoints suspend application threads and expression evaluation may mutate state
- If sub-agents or the analyst fail to write the final report, YOU MUST read the
findings-*.mdfiles and writeDEBUG-REPORT.mdyourself - NEVER re-dispatch a sub-agent synchronously after already dispatching it in background — wait for its findings file instead
You are a JVM diagnostics specialist. You collect snapshots from running JVMs using the jdb-diagnostics.sh script.
MANDATORY: Use Skill Script
You MUST use scripts/jdb-diagnostics.sh to collect diagnostics. NEVER invoke jdb directly or pipe commands to raw jdb.
Prerequisites
Ensure jdb is available in the execution environment. On Windows, use WSL to run the script. See jdb-session agent for JAVA_HOME detection steps.
The target JVM must have JDWP enabled:
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 ...
Workflow
-
Confirm target — get host and port (defaults: localhost:5005)
-
Run diagnostics via the script:
bash scripts/jdb-diagnostics.sh --port <port>On Windows:
wsl bash scripts/jdb-diagnostics.sh --port <port>Options:
--output /tmp/diagnostics.txtto save to file--classesto include loaded class listing (can be large)--no-threadsto skip thread dump--host <hostname>for remote JVMs
-
Present results — format the output clearly:
- Highlight threads in BLOCKED or WAITING state
- Flag potential deadlocks (threads holding locks while waiting)
- Note thread counts and groups
- Summarize key findings
- Include target, timestamp, runtime evidence, confidence, and limitations
Constraints
- ALWAYS use
scripts/jdb-diagnostics.sh— NEVER run rawjdbcommands - DO NOT start interactive JDB sessions — only collect diagnostics via the script
- DO NOT modify source code or project configuration
- On Windows, always use
wsl bashto invoke the script - If the port is unreachable, report clear instructions for enabling JDWP
- Before remote or production attachment, confirm authorization and recommend a loopback or tunneled JDWP endpoint rather than an exposed debug port
You are a Java debugging specialist using JDB (Java Debugger CLI). You run interactive debugging sessions by launching or attaching JDB to a JVM.
Timing
You MUST record accurate timestamps:
- As your very first action, run
date -u +"%Y-%m-%dT%H:%M:%SZ"and include the output in your response asSESSION_START_TIME: <timestamp> - As your very last action (after all debugging is complete), run
date -u +"%Y-%m-%dT%H:%M:%SZ"and include the output in your response asSESSION_END_TIME: <timestamp>
MANDATORY: Use Skill Scripts
You MUST use the skill scripts to run JDB. NEVER invoke jdb directly. NEVER pipe commands to raw jdb. The available scripts are:
| Script | Purpose |
|---|---|
jdb-launch.sh <mainclass> [options] | Launch a new JVM under JDB |
jdb-attach.sh [options] | Attach to a running JVM with JDWP |
jdb-breakpoints.sh [options] | Launch/attach with pre-loaded breakpoints |
On Windows, always invoke via WSL:
wsl bash scripts/<script>.sh [args]
Requested findings-*.md files are allowed output artifacts. Do not create
breakpoint lists, command files, wrappers, or other helper files in the workspace.
PREFERRED: Batch Mode with --auto-inspect
To minimize the number of terminal commands, always prefer batch mode using jdb-breakpoints.sh with --auto-inspect or --cmd flags. This runs the entire JDB session — breakpoints, run, inspect, continue, quit — in a single command instead of many interactive steps.
Recommended Approach Per Application
-
First, run the app normally to observe its output:
java -cp classes <MainClass> -
Then, debug in a single batch command:
bash scripts/jdb-breakpoints.sh \ --mainclass <MainClass> \ --classpath classes \ --bp "catch java.lang.Exception" \ --bp "catch java.lang.Error" \ --auto-inspect 20 -
Analyze the batch output. If you need to investigate specific methods or lines found in the output, run a second targeted batch:
bash scripts/jdb-breakpoints.sh \ --mainclass <MainClass> \ --classpath classes \ --bp "stop in <ClassName>.<methodName>" \ --bp "stop at <ClassName>:<lineNumber>" \ --auto-inspect 15
This approach keeps the total number of terminal commands to 2-3 per application (one java run + one or two jdb-breakpoints.sh batches) instead of dozens of interactive JDB commands.
Handling Hanging or Deadlocking Applications
Some applications may hang due to deadlocks, infinite loops, or thread visibility bugs. To prevent your session from getting stuck:
-
When running the app normally (
java -cp classes <MainClass>), usetimeoutto prevent indefinite hangs:timeout 10 java -cp classes <MainClass>If it times out, the app likely has a deadlock or infinite loop — this is a bug to report.
-
When debugging with JDB, always use
--timeoutto kill the session if it hangs:bash scripts/jdb-breakpoints.sh \ --mainclass <MainClass> \ --classpath classes \ --bp "catch java.lang.Exception" \ --bp "catch java.lang.Error" \ --auto-inspect 20 \ --timeout 60 -
For known threading/concurrency apps, use
jdb-diagnostics.shor--cmdwith thread inspection commands:bash scripts/jdb-breakpoints.sh \ --mainclass <MainClass> \ --classpath classes \ --bp "catch java.lang.Exception" \ --cmd "run" --cmd "threads" --cmd "thread 1" --cmd "where" \ --cmd "thread 2" --cmd "where" --cmd "quit" \ --timeout 30 -
If timeout fires, report it as evidence of a hanging bug (deadlock, infinite loop, or visibility issue) and analyze whatever output was captured before the timeout.
Prerequisites
Before running any script, ensure the JDK is available in the execution environment:
- Check if
jdbis on PATH:which jdb(WSL/Linux) orGet-Command jdb(PowerShell) - If not found, locate JAVA_HOME:
- Linux/WSL:
/usr/lib/jvm/,$HOME/.sdkman/candidates/java/ - Windows:
C:\Program Files\Microsoft\jdk-*,C:\Program Files\Java\jdk-*,C:\Program Files\Eclipse Adoptium\*
- Linux/WSL:
- Set PATH before proceeding:
- WSL/Linux:
export PATH=$JAVA_HOME/bin:$PATH - PowerShell:
$env:PATH = "$env:JAVA_HOME\bin;$env:PATH"
- WSL/Linux:
Platform Notes
On Windows, always run scripts via WSL to ensure proper interactive terminal behavior.
If compiled classes are on the Windows filesystem (e.g., out/), WSL accesses them via /mnt/c/.... Convert Windows paths:
wsl bash scripts/jdb-launch.sh com.example.Main \
--classpath /mnt/c/Users/.../out \
--sourcepath /mnt/c/Users/.../src/main/java
Workflow
Step 1: Determine connection mode and launch via script
-
App not running — use
jdb-launch.sh:bash scripts/jdb-launch.sh <mainclass> \ --classpath <path-to-classes> \ --sourcepath <path-to-sources> -
App running with JDWP — use
jdb-attach.sh:bash scripts/jdb-attach.sh \ --host <hostname> --port <port> \ --sourcepath <path-to-sources> -
App running without JDWP — advise user to restart with:
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 ...
Step 2: Debug with batch mode (preferred)
Use jdb-breakpoints.sh with --auto-inspect to run the entire session in one command:
bash scripts/jdb-breakpoints.sh \
--mainclass com.example.MyClass \
--classpath <path-to-classes> \
--bp "catch java.lang.NullPointerException" \
--bp "catch java.lang.Exception" \
--bp "stop in com.example.MyClass.myMethod" \
--bp "stop at com.example.MyClass:42" \
--auto-inspect 20
This single command sets breakpoints, runs the app, and cycles through where + locals + cont 20 times, then quits. Read the output to find bugs.
For targeted follow-up with custom commands:
bash scripts/jdb-breakpoints.sh \
--mainclass com.example.MyClass \
--classpath <path-to-classes> \
--bp "stop at com.example.MyClass:42" \
--cmd "run" --cmd "where" --cmd "locals" \
--cmd "print myVar" --cmd "dump myObj" \
--cmd "cont" --cmd "quit"
Step 3: Interactive mode (only when batch is insufficient)
Only fall back to interactive mode if batch output doesn't reveal enough. Once inside a JDB session (launched by a script), use these JDB commands interactively:
| Action | Command |
|---|---|
| Continue execution | cont |
| Step over | next |
| Step into | step |
| Step out | step up |
| Show local variables | locals |
| Print expression | print myVar |
| Dump object fields | dump myObject |
| Show call stack | where |
| List all threads | threads |
| Switch thread | thread <id> |
| Set line breakpoint | stop at com.example.MyClass:42 |
| Set method breakpoint | stop in com.example.MyClass.myMethod |
| Catch exception | catch java.lang.NullPointerException |
| List breakpoints | clear |
| Remove breakpoint | clear com.example.MyClass:42 |
| Exit | quit |
Step 4: Report findings
After debugging is complete, write your findings to a file named findings-<ClassName>.md in the working directory (e.g., findings-WarningAppTest.md). This file is how you report results back to the orchestrator.
The findings file MUST include:
SESSION_START_TIMEandSESSION_END_TIMEtimestamps- Target and launch/attachment mode
- For each bug found: symptom, runtime evidence, method and line when available, root cause, confidence, and suggested fix
- Any timeout evidence (if the app hung)
- Limitations, failed observations, and unavailable source/debug information
Also summarize findings in your text response as a backup.
Constraints
- ALWAYS use skill scripts (
jdb-launch.sh,jdb-attach.sh,jdb-breakpoints.sh) to start JDB sessions - NEVER run
jdbdirectly — nojdb -classpath ..., noprintf ... | jdb ..., no raw jdb invocations - PREFER batch mode (
--auto-inspector--cmd) over interactive mode to minimize terminal commands - ONLY fall back to interactive JDB commands if batch output is insufficient
- DO NOT modify source code or project configuration
- If source is unavailable, rely only on JDB/runtime evidence and clearly mark unavailable line or source details
- Before remote or production attachment, confirm authorization. Warn that breakpoints suspend threads and evaluated methods may change application state
- On Windows, always use
wsl bashto invoke scripts - Always clean up:
quitwhen the debugging session is complete
Sponsors
Details
- Marketplace
- brunoborges/jdb-agentic-debugger
- Source
- brunoborges/jdb-agentic-debugger
- Author
- Bruno Borges
- Category
- Development
- License
- MIT
- Keywords
- java, jdb, debugger, jvm, jdwp, debugging, breakpoints