Java Debug Skill — AI skill for Claude Code

java-debug

English | [简体中文](README.zh-CN.md)

A **Java remote breakpoint debugging Skill** for AI agents such as Claude Code. It attaches to a remote JVM with JDWP enabled. The AI plans and sets breakpoints, waits for hits, collects call stacks and local variables, evaluates expressions and single-steps. It then reports a root cause based only on **runtime data it actually collected**.

At its core is the in-house `.agents/skills/java-debug/scripts/jdi-client.jar`. It uses only the JDK's built-in `com.sun.jdi` and has zero external dependencies. The jar is not shipped; it is built locally from the bundled source the first time the skill runs. It runs as a resident HTTP server, and every operation is a single JSON command, so `curl` is all you need to drive it.

---

Why not just use jdb

`jdb` is made for a human typing in a terminal, and it is awkward for an AI to drive. Its output is text that has to be parsed, timing has to be guessed with tmux + sleep, and by default it freezes the whole JVM. This Skill redesigns the interaction layer for AI-driven debugging:

Aspect	jdb	java-debug
Suspend scope	SUSPEND_ALL: a hit freezes the whole JVM	SUSPEND_EVENT_THREAD: only the hit thread freezes; other business threads keep serving
Interaction	Text output that has to be parsed; relies on tmux + sleep to race timing	Structured JSON requests and responses; no tmux, no sleep races
Hit information	where / locals must be typed one by one	The hit response already includes the stack and locals
Waiting	Polling	Event-driven blocking wait (wait-breakpoint) with a timeout
Workflow guardrails	None	Built-in workflow: the user must confirm the breakpoint plan, the session must end with disconnect, and conclusions must be based on observed values

---

Security

Remote debugging is inherently dangerous: JDWP has no authentication, so anyone who can connect can run arbitrary code. This Skill m