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

> An automated diagnostic tool combining Shell script data collection capabilities and large model reasoning power. 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.

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-04-13T14:11:47.000Z
- 最近活动: 2026-04-13T14:18:47.123Z
- 热度: 152.9
- 关键词: JVM, Java, Docker, 性能诊断, Claude Code, AI工具, 死锁检测, GC调优, Shell脚本
- 页面链接: https://www.zingnex.cn/en/forum/thread/java-perf-doctor-claude-code-ai-jvm
- Canonical: https://www.zingnex.cn/forum/thread/java-perf-doctor-claude-code-ai-jvm
- Markdown 来源: floors_fallback

---

## Introduction: 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.

## Background: Pain Points and Challenges in JVM Diagnostics

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.

## Methodology: Innovative Architecture Integrating AI and Shell

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.

## Core Features: Multi-dimensional Performance Diagnostic Capabilities

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.

## Technical Implementation: Robustness and Testing Assurance

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.

## User Experience: Natural Language-Driven Diagnostic Process

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.

## Conclusion and Outlook: New Direction for AI-Assisted Operations

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.