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-debugger

Run it inside Claude Code after adding the marketplace with /plugin marketplace add brunoborges/jdb-agentic-debugger.

Contents

Discovered from source

Skills 2

Java Debugger (JDB) Skill

Debug Java applications interactively using the JDK's built-in command-line debugger.

Critical Rules for Agents

  1. 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.
  2. ALWAYS use the skill scripts in scripts/. Never write custom JDB wrapper scripts, FIFO-based launchers, or shell scripts to drive JDB.
  3. Compile first, then debug. Ensure classes are compiled before launching JDB.
  4. 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 --timeout flags. The scripts handle all temp files internally in /tmp/ and clean up after themselves.
  • Use --timeout for 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 a TIMEOUT: marker when triggered.
  • Compile with -g for full debug info. Without it, locals will 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 -sourcepath or use command so list can show source code.
  • Classpath: Ensure compiled classes are accessible for expression evaluation.
  • Thread context: Many commands operate on the "current thread". Use thread to switch.
  • Suspend mode: When attaching with suspend=y, the JVM pauses until JDB connects. Use suspend=n for non-blocking attachment.
  • Expression evaluation: print and eval can 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

Java Debugger (JDB) Skill

Debug Java applications interactively using the JDK's built-in command-line debugger.

Critical Rules for Agents

  1. NEVER create debugger helper files in the workspace (no bp.txt, cmds.txt, wrapper scripts, etc.). Requested report artifacts such as findings-*.md and DEBUG-REPORT.md are allowed. Use the inline CLI flags (--bp, --cmd, --auto-inspect, --timeout) provided by the skill scripts.
  2. ALWAYS use the skill scripts in scripts/. Never write custom JDB wrapper scripts, FIFO-based launchers, or shell scripts to drive JDB.
  3. Compile first, then debug. Ensure classes are compiled before launching JDB.
  4. 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 --timeout flags. The scripts handle temporary input internally and clean up.
  • Use --timeout for 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 a TIMEOUT: marker when triggered.
  • Compile with -g for full debug info. Without it, locals will 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 -sourcepath or use command so list can show source code.
  • Classpath: Ensure compiled classes are accessible for expression evaluation.
  • Thread context: Many commands operate on the "current thread". Use thread to switch.
  • Suspend mode: When attaching with suspend=y, the JVM pauses until JDB connects. Use suspend=n for non-blocking attachment.
  • Expression evaluation: print and eval can 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

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

  1. Read the input — stack trace, thread dump, log snippet, diagnostic file, or findings text from sub-agents
  2. Cross-reference when permitted — search source only when it is available and the request allows source access; otherwise use runtime evidence exclusively
  3. 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
  4. 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):

  1. Read all findings-*.md files in the working directory — these are written by jdb-session sub-agents
  2. Consolidate all findings into a single DEBUG-REPORT.md
  3. Also use any findings provided directly in your prompt text as supplementary input
  4. You MUST write the DEBUG-REPORT.md file — 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:

  1. 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 as SESSION_START_TIME: <timestamp>.
  2. 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 as SESSION_END_TIME: <timestamp>.
  3. Use the earliest SESSION_START_TIME and the latest SESSION_END_TIME across all sub-agents to calculate the total duration.
  4. Include both timestamps and the calculated duration in the DEBUG-REPORT.md timing header.

Skill Scripts

All JDB operations MUST use the scripts from the jdb-debugger skill:

ScriptPurpose
jdb-launch.shLaunch a new JVM under JDB
jdb-attach.shAttach JDB to a running JVM with JDWP
jdb-breakpoints.shLaunch/attach JDB with pre-loaded breakpoints
jdb-diagnostics.shCollect 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:

  1. Identify independent targets — each main class or application that can be debugged independently
  2. Dispatch one sub-agent per target in parallel — hand off each application to a separate jdb-session agent simultaneously, not sequentially
  3. Each sub-agent works independently — runs the app, launches JDB, sets breakpoints, inspects variables, and reports its findings for that single application
  4. Collect and consolidate — once all sub-agents complete, hand off all findings to jdb-analyst to 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 as SESSION_START_TIME: <timestamp> and SESSION_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 60 with jdb-breakpoints.sh to prevent indefinite hangs
  • Always instruct sub-agents to use timeout 10 when 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:

  1. Dispatches all sub-agents in background (in parallel)
  2. Does NOT re-dispatch sub-agents synchronously — never duplicate work
  3. Waits, then checks for findings-*.md files in the working directory using the read tool
  4. Once all expected findings files exist, hands off to jdb-analyst to consolidate them into DEBUG-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 to findings-WarningAppTest.md."
  • Sub-agent 2 → jdb-session: "Debug ConsoleAppTest. Write findings to findings-ConsoleAppTest.md."
  • Sub-agent 3 → jdb-session: "Debug AliasingCorruptionTest. Write findings to findings-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

  1. Multiple independent apps to debug → dispatch parallel jdb-session sub-agents (one per app), then jdb-analyst to consolidate
  2. Single app: step through code, set breakpoints, catch exceptions, or inspect variables → hand off to jdb-session
  3. User wants a thread dump, deadlock check, or quick JVM health snapshot → hand off to jdb-diagnostics
  4. 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 .java source 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-*.md files and write DEBUG-REPORT.md yourself
  • 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

  1. Confirm target — get host and port (defaults: localhost:5005)

  2. 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.txt to save to file
    • --classes to include loaded class listing (can be large)
    • --no-threads to skip thread dump
    • --host <hostname> for remote JVMs
  3. 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 raw jdb commands
  • 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 bash to 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:

  1. As your very first action, run date -u +"%Y-%m-%dT%H:%M:%SZ" and include the output in your response as SESSION_START_TIME: <timestamp>
  2. 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 as SESSION_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:

ScriptPurpose
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

  1. First, run the app normally to observe its output:

    java -cp classes <MainClass>
    
  2. 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
    
  3. 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:

  1. When running the app normally (java -cp classes <MainClass>), use timeout to 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.

  2. When debugging with JDB, always use --timeout to 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
    
  3. For known threading/concurrency apps, use jdb-diagnostics.sh or --cmd with 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
    
  4. 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:

  1. Check if jdb is on PATH: which jdb (WSL/Linux) or Get-Command jdb (PowerShell)
  2. 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\*
  3. Set PATH before proceeding:
    • WSL/Linux: export PATH=$JAVA_HOME/bin:$PATH
    • PowerShell: $env:PATH = "$env:JAVA_HOME\bin;$env:PATH"

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:

ActionCommand
Continue executioncont
Step overnext
Step intostep
Step outstep up
Show local variableslocals
Print expressionprint myVar
Dump object fieldsdump myObject
Show call stackwhere
List all threadsthreads
Switch threadthread <id>
Set line breakpointstop at com.example.MyClass:42
Set method breakpointstop in com.example.MyClass.myMethod
Catch exceptioncatch java.lang.NullPointerException
List breakpointsclear
Remove breakpointclear com.example.MyClass:42
Exitquit

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_TIME and SESSION_END_TIME timestamps
  • 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 jdb directly — no jdb -classpath ..., no printf ... | jdb ..., no raw jdb invocations
  • PREFER batch mode (--auto-inspect or --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 bash to invoke scripts
  • Always clean up: quit when 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