claudeers.
// Other

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,…

// Other[ cli ][ api ][ web ][ claude ]#claude#other$open-sourceupdated 24 days ago
Actively maintained
95/100
last commit 25 days ago
last release none
releases 0
open issues 0

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.
// or clone
git clone https://github.com/Aresxue/java-debug-skill

// compatibility

Platformscli, api, web
Operating systems—
AI compatibilityclaude
License—
Pricingopen-source
LanguageJava

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

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:

Aspectjdbjava-debug
Suspend scopeSUSPEND_ALL: a hit freezes the whole JVMDefault SUSPEND_EVENT_THREAD: only the hit thread freezes; other business threads keep serving. all and non-suspending logpoints are opt-in per breakpoint
InteractionText output that has to be parsed; relies on tmux + sleep to race timingStructured JSON requests and responses; no tmux, no sleep races
Hit informationwhere / locals must be typed one by oneThe hit response already includes the stack and locals
WaitingPollingEvent-driven blocking wait (wait-breakpoint) with a timeout
Workflow guardrailsNoneBuilt-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 an ssh -L tunnel
  • The Host header must be 127.0.0.1, localhost or [::1], and any request with an Origin header 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-breakpoint and step both time out. A timeout response lists frozen_threads, the threads that were reported but never resumed, so none get forgotten
  • At most 2 step / eval / to_string commands run at once, which always leaves a worker free for resume / disconnect. A stuck eval cannot take down the command port
  • eval has 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 / ThreadGroup stop / suspend / resume, plus the JDK internals behind them such as java.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), a log_message template whose output is pulled with logs, and a per-breakpoint suspend_policy of thread (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:N counts only the Nth matching hit and then expires the breakpoint (as IDEA's Pass count); temporary:true deletes the breakpoint after its first hit. list-breakpoints shows 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_id shows which copy was hit. When a copy cannot get the breakpoint, deferred_failures gives 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. locals with a path pages through one value's children without invoking anything; "to_string":true opts in to IDEA's default view (size = N for collections, overridden toString())
  • Concurrent hit isolation: step returns only the requested thread's events. Other threads' hits stay queued in order for wait-breakpoint
  • State inspection: local variables of any frame, full call stack (depth can be limited) and the thread list. stack also snapshots a thread that no breakpoint stopped, and threads with dump:true takes 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 with class_loader_id
  • Single-stepping: over / into / out, and to_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: pause freezes one running thread for inspection until resume
  • 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, InvalidArgs and more, each with a defined meaning and remedy
  • Reconnect: after the target JVM restarts, one connect command 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.jar added) 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.jar is 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 plain javac. See Building.
  • After npx skills update nothing 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

  1. 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
    
  2. 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:123
    

    Options: --bp sets a breakpoint up front (repeatable), --repo is the local source path, --max-bp caps breakpoints per round, --wait-timeout sets how many seconds to wait for a hit, and --manual only generates the command list.

  3. 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.

12 views
★ 11 stars
unclaimed
updated 24 days ago

// embed badge

java-debug-skill on Claudeers
[![Claudeers](https://claudeers.com/api/badge/java-debug-skill.svg)](https://claudeers.com/java-debug-skill)

// retro hit counter

java-debug-skill hit counter
[![Hits](https://claudeers.com/api/counter/java-debug-skill.svg)](https://claudeers.com/java-debug-skill)

// reviews

// guestbook

0/500

// related in Other

🔓

符合nature论文学术表达和科研绘图的Skill

// otherYuan1z0825/⟨Python⟩★ 54,085◷ Apache-2.0[ claude ]
🔓

Anti-AI-slop design skill for Claude Code, Cursor, and Codex.

// otherNutlope/⟨CSS⟩★ 49,642◷ MIT[ claude ]
🔓

Huashu Design · HTML-native design skill for Claude Code · Claude Code 里 HTML 原生的设计 skill · 高保真原型 / 幻灯片 / 动画 + 20 设计哲学 + 5 维评审 + MP4 导出 · Agent-agnostic

// otheralchaincyf/⟨HTML⟩★ 28,944◷ MIT[ claude ]
🔓

Open source Ghostty-based macOS terminal with vertical tabs and notifications for AI coding agents. Built for multitasking, organization, and programmability.

// othermanaflow-ai/⟨Swift⟩★ 28,842◷ NOASSERTION[ claude ]
→ see how java-debug-skill connects across the ecosystem