java-perf-doctor: An AI-native JVM Diagnostic Tool Built Exclusively for Claude Code

java-perf-doctor is an automated diagnostic tool that combines Shell script data collection capabilities with large language model reasoning. It can cross host boundaries to perform JVM performance checks deep inside Docker containers, enabling deadlock localization, CPU hot spot tracking, and GC health checks. As an exclusive tool for Claude Code, it features a zero-intrusion design—no need to pre-install monitoring agents inside containers, making it suitable for minimal Docker images in production environments.

In today's era where microservice architecture and containerized deployment are mainstream, Java application performance diagnostics have become increasingly complex. Traditional tools require installing complex agents inside containers or manually executing commands to interpret results—this process is cumbersome and demands deep tuning experience. When issues like latency or CPU spikes occur in production environments, ops personnel face the dilemma of either risking tool installation or relying on log guesswork, spurring the need for intelligent automated solutions.

The core innovation of java-perf-doctor lies in integrating Shell script data collection capabilities with large language model reasoning. Its zero-intrusion design uses docker exec to automatically schedule native JDK tools (such as jstack, jstat, jcmd) for data collection—no pre-installed agents needed. It is particularly suitable for minimal Docker images where debugging tools have been removed for security reasons.

1. Accurate Deadlock Localization: Automatically scans thread stacks, identifies thread addresses holding or waiting for locks, and correlates with source code line numbers;
2. CPU Hot Spot Tracking: Automatically converts Linux TID to JVM NID (hexadecimal conversion), locking onto hot spot code;
3. GC Trend Health Check: Analyzes memory proportions of Eden/Old generations, monitors Full GC frequency, and provides JVM parameter tuning recommendations.

The project uses defensive script design with built-in /proc filesystem fallback logic—even if standard JDK tools are unavailable, it can still read kernel data for collection. It also includes a complete set of test cases in evals.json, verifying the accuracy and robustness of diagnostic results through automated assertions.

As a Skill for Claude Code, java-perf-doctor supports natural language commands. When users input commands like "Diagnose the performance of the takeout-app container", Claude Code automatically invokes the tool to perform diagnostics and generate a structured report. This lowers the barrier to JVM diagnostics, allowing developers without deep tuning experience to obtain professional recommendations.

java-perf-doctor represents the development direction of AI-assisted operation tools: encoding domain knowledge into Skills, letting large models handle reasoning and report generation, while humans focus on decision-making. For Java microservice teams, it provides a lightweight, zero-intrusion diagnostic solution that deserves to be included in the operation toolbox. In the future, as AI Agent technology matures, more intelligent tools will simplify system operations.