jdbg

jdbg CLI - interactive Java debugging for Pi

jdbg is a cross-platform CLI wrapper around the JDK's jdb, with an optional JDI sidecar backend for structured runtime data. It keeps a stateful background daemon alive, so a debug session survives across separate shell commands.

Pi has no official jdbg MCP setup. Use the jdbg CLI directly.

Core loop: run one jdbg command, read the result, then decide the next command. Do not batch debugger commands, add sleeps, or guess timing. jdbg waits for the jdb prompt internally; long-running commands return TIMEOUT without killing the session.

When To Use

Use jdbg when you need runtime truth:

• the value of a variable, field, array element, collection, or expression at a line
• why an exception or NullPointerException is thrown, with stack and locals at the throw site
• how execution reaches code, by stepping line by line
• what a blocked or deadlocked thread is waiting on
• who reads or modifies a field, using watchpoints

Do not use it for plain compile errors or code that is simple enough to reason about statically.

Start A Session

Compile Java with debug info when possible:

javac -g Main.java

Launch a program under the debugger:

jdbg launch Main --classpath . --sourcepath src

Launch with application arguments after --:

jdbg launch com.example.Main --classpath target/classes --sourcepath src/main/java -- arg1 arg2

Launch through the JDI sidecar when you need structured JDI data:

jdbg launch Main --backend jdi --classpath . --sourcepath src

Attach to a running JVM with JDWP enabled:

jdbg attach --host localhost --port 5005 --sourcepath src/main/java

Use the JDI sidecar for structured attach debugging:

jdbg attach --backend jdi --host localhost --port 5005 --sourcepath src/main/java

If --sourcepath is omitted, jdbg uses the shell's current working directory as the source root and sends it to the daemon as an absolute path. Relative --sourcepath values are also absolutized before the daemon sees them, so source lookup is stable even when the daemon was started from another directory. On JDI sessions, source lookup also tries the target JVM's user.dir and Maven/Gradle module roots inferred from java.class.path (for example mall-portal/target/classes -> mall-portal/src/main/java).