
java-debug-skill
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,…
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up java-debug-skill (git-clone project) into my current project. Found on https://claudeers.com/java-debug-skill Repo: https://github.com/Aresxue/java-debug-skill Homepage/docs: — Detected install method: git-clone → git clone https://github.com/Aresxue/java-debug-skill Category: other. Platforms: cli, api, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
git clone https://github.com/Aresxue/java-debug-skill
// compatibility
| Platforms | cli, api, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | — |
| Pricing | open-source |
| Language | Java |
java-debug
English | 简体中文
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 | Default SUSPEND_EVENT_THREAD: only the hit thread freezes; other business threads keep serving. all and non-suspending logpoints are opt-in per breakpoint |
| 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 makes its safety boundaries hard constraints wherever possible, instead of relying on the operator's discipline.
Command port hardening (jdi-client's own port, 15005 by default)
- The bind address is hard-coded to
127.0.0.1, and no switch can open it up. To use it from another machine, go through anssh -Ltunnel - The
Hostheader must be127.0.0.1,localhostor[::1], and any request with anOriginheader gets a 403. This blocks cross-site POSTs from browsers and DNS rebinding - A POST must carry
Content-Type: application/json(otherwise 415). The body is capped at 1 MB, and the request must arrive within 30s so slow connections cannot exhaust the worker threads - JSON parsing is strict: nesting deeper than 64 levels, illegal escapes, unescaped control characters and trailing content after the JSON are all rejected
Protecting the target JVM
- Only the hit thread is frozen by default (
SUSPEND_EVENT_THREAD), so the service as a whole keeps running. Freezing the whole VM (all) is per breakpoint and needs explicit user confirmation - The client keeps at most 64 hit scenes. Beyond that, new hits are released without collecting a scene and the response reports
dropped_events. This stops "wait for one, don't resume, wait again" from slowly draining the thread pool wait-breakpointandstepboth time out. A timeout response listsfrozen_threads, the threads that were reported but never resumed, so none get forgotten- At most 2
step/eval/to_stringcommands run at once, which always leaves a worker free forresume/disconnect. A stuck eval cannot take down the command port evalhas a hard deny list for methods that terminate the JVM, start or kill a process, stop, suspend or resume a thread, or load native code:System.exit,Runtime.exit/halt/exec/load,ProcessBuilder.start,Thread/ThreadGroupstop/suspend/resume, plus the JDK internals behind them such asjava.lang.Shutdown(JDI ignores access control)- A breakpoint hit, its condition and its log template only read fields and never call
toString(), so a hit by itself runs no business code - After
disconnect, every frozen thread in the target JVM resumes automatically
Workflow hard rules (written into the Skill; the AI must follow them)
- The breakpoint plan must be shown to the user and confirmed before connecting or setting breakpoints
- The session must end with
disconnect, whether it finishes normally, fails midway or is interrupted - Methods with side effects must not be evaluated (DB writes, sending MQ, changing state, clearing caches)
- Before attaching to production, the user must confirm that the JDWP port is behind an IP allowlist or an SSH tunnel, and must be told that breakpoints freeze business threads
- Sensitive data from auth, payment or privacy-related frames (tokens, ID numbers, bank card numbers, passwords) must not be pasted verbatim into the conversation or the report
Limits: the deny list guards against slips. It is not a sandbox, and other methods with side effects can still be called. The 64 cap limits the scenes the client keeps, not the number of threads the target suspends at once, so a burst of concurrent hits can still suspend many threads instantly. In production, put breakpoints on cold, lock-free paths and resume quickly.
Features
- Breakpoints: method-entry and line breakpoints. If the class isn't loaded yet, the breakpoint is deferred automatically. Every overload and every executable location on a line (including lambdas) gets a breakpoint
- Conditions, logpoints, suspend policies: a read-only
condition(field paths, literals, comparisons,&&/||/!; never invokes target code), alog_messagetemplate whose output is pulled withlogs, and a per-breakpointsuspend_policyofthread(default) /all/none - Exception breakpoints: break on a thrown exception type and its subclasses, caught and/or uncaught, optionally limited to throwing classes with
location_filter; the hit reports the exception's class, message and catch location - Field watchpoints: break when a field is written (default) or also read (
access:true), from any code; conditions and log templates can use$value/$old/$object, and the hit reports the old and new value - Pass count and one-shot breakpoints:
pass_count:Ncounts only the Nth matching hit and then expires the breakpoint (as IDEA's Pass count);temporary:truedeletes the breakpoint after its first hit.list-breakpointsshows every breakpoint with its rule, status (active/deferred/expired) and hit count - Multiple classloaders / hot deployment: every loaded copy of a same-name class gets the breakpoint, copies loaded later are covered automatically, and
class_loader_idshows which copy was hit. When a copy cannot get the breakpoint,deferred_failuresgives the reason (wrong method name, no bytecode on that line, not compiled with-g, etc.) - Field-tree display: objects are expanded by field to depth 2, and
toString()is never called automatically.localswith apathpages through one value's children without invoking anything;"to_string":trueopts in to IDEA's default view (size = Nfor collections, overriddentoString()) - Concurrent hit isolation:
stepreturns only the requested thread's events. Other threads' hits stay queued in order forwait-breakpoint - State inspection: local variables of any frame, full call stack (depth can be limited) and the thread list.
stackalso snapshots a thread that no breakpoint stopped, andthreadswithdump:truetakes a thread dump (stacks, owned and awaited monitors) with deadlock detection during a brief freeze of the VM - Expression evaluation (like IDEA's Evaluate Expression): local variables, field access, instance methods, chained calls, static methods and static fields, array elements and
length; arguments are Java literals (1L,1.5f,'c', …) or read-only paths, with overloads chosen as javac does (widening, boxing, varargs). Breakpoints inside an evaluated method are skipped instead of hanging the call. When a same-name class has several copies, pick one withclass_loader_id - Single-stepping:
over/into/out, andto_line(Run to Cursor, through a temporary breakpoint for that thread only). The response includes the stack and locals at the new location. Running into another breakpoint mid-step behaves as in IDEA - Pause:
pausefreezes one running thread for inspection untilresume - Hot-deployment friendly: on JDK 9+ targets, static calls go through a MethodHandle and do not pin the called class's classloader, so old versions can still unload
- Clear error codes:
ConnectFailed,Timeout,Superseded,VmDisconnected,Busy,AmbiguousClass,InvalidArgsand more, each with a defined meaning and remedy - Reconnect: after the target JVM restarts, one
connectcommand reconnects - No direct connection (
--manual): generates a command list for the user to run on the target or a jump host; the output is then pasted back for analysis - Compatibility: the client runs on JDK 8 (with
tools.jaradded) or JDK 9+, and can debug JVMs older than itself
Installation
Install from github.com/Aresxue/java-debug-skill with npx skills (requires Node.js). A global install is recommended, so the skill is available in every project:
# Recommended: global install for Claude Code (~/.claude/skills/java-debug)
npx skills add https://github.com/Aresxue/java-debug-skill --skill java-debug -g -a claude-code -y
Other options:
# Global install for several agents at once (omit -a to pick agents interactively)
npx skills add https://github.com/Aresxue/java-debug-skill --skill java-debug -g -a claude-code -a codex -a cursor
# Project scope (./.claude/skills/java-debug), committed with the project and shared with the team
npx skills add https://github.com/Aresxue/java-debug-skill --skill java-debug -a claude-code
# List installed skills / update / uninstall
npx skills ls -g
npx skills update java-debug -g
npx skills remove java-debug -g
Notes:
jdi-client.jaris not shipped; it is built locally from the bundled source the first time the skill runs, so the machine needs a JDK (a JRE is not enough). Maven is used if present, otherwise plainjavac. See Building.- After
npx skills updatenothing needs deleting: the next run sees that the source no longer matches the checksum recorded with the jar and rebuilds it. - Manual install also works: copy (or symlink)
.agents/skills/java-debug/into the agent's skills directory, e.g.~/.claude/skills/java-debug/.
Quick start
-
Start the target JVM with JDWP and compile it with
-g(the Maven / Gradle default):# JDK 9+ (under zsh, quote the whole argument) java "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" -jar app.jar # JDK 8 java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 -jar app.jar -
Install the skill (see Installation), then invoke it from the agent:
/java-debug 10.0.1.5:5005 --repo /path/to/repo /java-debug 10.0.1.5:5005 --bp com.example.OrderService.query --bp com.example.OrderService:123Options:
--bpsets a breakpoint up front (repeatable),--repois the local source path,--max-bpcaps breakpoints per round,--wait-timeoutsets how many seconds to wait for a hit, and--manualonly generates the command list. -
The AI then works through these steps: read the code to find the entry point → show the breakpoint plan for your confirmation → connect and set breakpoints → ask you to trigger the request → collect state, step and evaluate → disconnect → report the execution path, variable snapshot, root cause and fix.
See SKILL.md for the full workflow, command reference and error handling.
Layout
java-debug/
├── .agents/skills/java-debug/ # The Skill itself (install this directory)
│ ├── SKILL.md # Skill definition: workflow, command reference, safety rules, error handling
│ ├── scripts/
│ │ ├── ensure-jdi-client.sh # Builds scripts/jdi-client.jar on first use and after a source change (not shipped, git-ignored)
│ │ └── jdi-client.jar # Local build output
│ └── jdi-client/ # Client source (Maven project)
│ ├── build.sh
│ └── src/main/java/cn/ares/jvm/jdi/
│ ├── transport/ # HTTP / stdio transport, zero-dependency JSON
│ ├── command/ # Command routing and command handlers
│ ├── connection/ # Connection lifecycle, concurrency permits
│ ├── session/ # JDWP connection, thread and classloader lookup
│ ├── breakpoint/ # Breakpoints and deferred breakpoints
│ ├── execution/ # Event loop; freeze / wait / resume / step state machine
│ ├── inspect/ # Stack, locals, value formatting
│ └── eval/ # Expression evaluation, dangerous-method guard, static calls
└── jdi-client-test/ # Test module (outside the Skill, not installed)
├── pom.xml # Compiles jdi-client's sources in
└── src/test/java/cn/ares/jvm/jdi/
├── ... # Unit tests, in the package of the class under test
└── it/ # JDWP integration tests; target/ holds the program they debug
Building
bash .agents/skills/java-debug/scripts/ensure-jdi-client.sh
If scripts/jdi-client.jar is missing, the script builds it with Maven (jdi-client/build.sh) and falls back to the local JDK's javac + jar when Maven is absent or fails. It needs a JDK (not just a JRE); on JDK 8 it adds tools.jar automatically, while JDK 9+ ships com.sun.jdi built in. The output is Java 8 bytecode. Each build records a checksum of the source in scripts/jdi-client.jar.stamp (git-ignored); when the source changes, the next run rebuilds the jar.
Testing
mvn -f jdi-client-test/pom.xml test
Runs the unit tests and the JDWP integration tests together. It needs a JDK (on JDK 8 tools.jar is added automatically). The integration tests start one target JVM per test class, with JDWP listening on a random port on 127.0.0.1 only, and kill it when the class is done. CI (.github/workflows/test.yml) runs the same command on Linux and Windows, each on JDK 8, 11, 17 and 21.
For a coverage report, add -Pcoverage; JaCoCo writes it to jdi-client-test/target/site/jacoco/index.html.
// faq
What is java-debug-skill?
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.. It is open-source on GitHub.
Is java-debug-skill free to use?
java-debug-skill is open-source, so it is free to use.
What category does java-debug-skill belong to?
java-debug-skill is listed under other in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/java-debug-skill)
// retro hit counter
[](https://claudeers.com/java-debug-skill)
// reviews
// guestbook
// related in Other
Anti-AI-slop design skill for Claude Code, Cursor, and Codex.
Huashu Design · HTML-native design skill for Claude Code · Claude Code 里 HTML 原生的设计 skill · 高保真原型 / 幻灯片 / 动画 + 20 设计哲学 + 5 维评审 + MP4 导出 · Agent-agnostic
Open source Ghostty-based macOS terminal with vertical tabs and notifications for AI coding agents. Built for multitasking, organization, and programmability.