Skip to content
Back to search

tda

TDA - Thread Dump Analyzer (for Java). Analyze your Thread Dumps with a GUI or use it as MCP Server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/irockel/tda with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/irockel/tda'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/irockel--tda/badge.svg)](/listings/irockel--tda)

HTML

<a href="/listings/irockel--tda"><img src="/api/listings/irockel--tda/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

TDA can be installed or used in several ways:

1. Self-contained JAR

The simplest way to use TDA is to download the `tda.jar` from the **Releases** page. Since it's a self-contained JAR, you can run it directly on any system with Java installed.

2. VisualVM Plugin

TDA is available as a plugin for VisualVM. You can install it directly from the **VisualVM Plugin Center** (Tools -> Plugins). This integrates TDA's analysis capabilities directly into your VisualVM environment. The last available version in the plugin center is 2.4. For installing the recent version, download the three nbm files from the Releases page and install them manually in the VisualVM plugins settings.

3. macOS Binary (DMG)

TDA provides a native macOS DMG package for easier installation. This package includes its own Java runtime, so no separate Java installation is required to run it.

Installation (Unsigned Binary)

Since the DMG is currently unsigned, macOS will block it by default with a warning that the "developer cannot be verified". To install and run TDA:

1. Download the `TDA-<version>.dmg` from the Releases page. 2. Open the DMG and drag **TDA.app** to your **Applications** folder. 3. **Right-click** (or Control-click) on `TDA.app` in your Applications folder and select **Open**. 4. A dialog will appear asking if you are sure you want to open it. Click **Open**. 5. After this first launch, you can open TDA normally from Launchpad or Spotlight.

If this fails, you might need to confirm the installation from the system settings. For this just follow the instructions after clicking on the '?' Icon on the upper right corner of the error dialog.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 311 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![Java CI with Maven](https://github.com/irockel/tda/actions/workflows/build.yml/badge.svg)](https://github.com/irockel/tda/actions/workflows/build.yml)
  2. [![Renovate](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://github.com/irockel/tda/issues?q=is%3Aissue+is%3Aopen+label%3Adependencies)
  3. [![Dependencies](https://img.shields.io/librariesio/github/irockel/tda)](https://libraries.io/github/irockel/tda)
  4. [![License](https://img.shields.io/github/license/irockel/tda)](LICENSE)
  5. # TDA - Thread Dump Analyzer
  6. > [!IMPORTANT]
  7. >
  8. > **2026-05-11 - TDA 3.2 available.**
  9. > * **VisualVM Plugin**: proper integration in VisualVM working again.
  10. > * **UI**: Updated jsvg version to 2.1.0.
  11. >
  12. > **2026-04-18 - TDA 3.1 available.**
  13. > * **VisualVM Plugin**: proper integration in VisualVM working again.
  14. > * **Logfile Parsing**: Support for UTF16 files.
  15. > * **UI**: some small fixes.
  16. >
  17. > **2026-01-30 - TDA 3.0 is now available!** 🚀
  18. > This major release brings significant enhancements:
  19. > * **Extended MCP Server**: Now with **Carrier Thread Pinning** detection and support for **SMR (Safe Memory Relocation)** parsing.
  20. > * **Modernized UI**: Completely refreshed look and feel using **FlatLaf**.
  21. > * **Usability Improvements**: Fixed several long-standing issues, including improved split-pane management and faster parsing.
  22. > * **Native macOS Support**: Now providing a dedicated macOS binary.
  23. > * **Logging**: Especially for troubleshooting in MCP Mode.
  24. TDA (Thread Dump Analyzer) for Java is a powerful yet lightweight Swing GUI and **MCP Server** for analyzing Thread Dumps and Heap
  25. Information generated by the Java VM. It is designed to assist in diagnosing performance issues, deadlocks, and
  26. memory problems in Java applications. With its MCP capabilities, TDA can be seamlessly integrated into AI-powered
  27. development workflows.
  28. TDA supports Java 1.4.x through Java 21+, including specialized support for **Virtual Threads** (Java 19+) and **JSON-based thread dumps**
  29. (Java 21+, experimental).
  30. ## 📋 Table of Contents
  31. - [🚀 Key Features](#-key-features)
  32. - [📦 Installation](#-installation)
  33. - [1. Self-contained JAR](#1-self-contained-jar)
  34. - [2. VisualVM Plugin](#2-visualvm-plugin)
  35. - [3. macOS Binary (DMG)](#3-macos-binary-dmg)
  36. - [🛠 Usage Modes](#-usage-modes)
  37. - [1. Standalone Application](#1-standalone-application)
  38. - [2. JConsole Plugin](#2-jconsole-plugin)
  39. - [3. VisualVM Plugin](#3-visualvm-plugin-1)
  40. - [4. JSON-based Thread Dumps (Experimental)](#4-json-based-thread-dumps-experimental)
  41. - [5. MCP Server (Headless Analysis)](#5-mcp-server-headless-analysis)
  42. - [6. Agent Skill (Multi-Agent Support)](#6-agent-skill-multi-agent-support)
  43. - [🏗 Building from Source](#-building-from-source)
  44. - [🛠️ Troubleshooting](#-troubleshooting)
  45. - [📜 Changelog](CHANGELOG.md)
  46. - [📜 License](LICENSE)
  47. ## 🚀 Key Features
  48. * **Comprehensive Thread Dump Parsing**: Parse multiple thread dumps from log files and display them in an intuitive tree structure.
  49. * **Virtual Threads Support**: Analyze virtual thread states, pinning issues, and carrier thread relationships.
  50. * **Statistical Analysis**: Detailed statistics about thread states, monitors, and waiting/locking threads.
  51. * **Long-Running Thread Detection**: Identify threads that persist across multiple dumps, helping find "hung" or inefficient code.
  52. * **Deadlock Detection**: Automatic identification of deadlocks with detailed monitor information.
  53. * **JSON-based Thread Dumps**: Support for parsing JSON-formatted thread dumps created with `jcmd <pid> Thread.dump_to_file -format=json <file>`.
  54. *Note: JSON dumps currently provide basic information (name, tid, stack trace) but lack details like thread states or native IDs. For comprehensive analysis, textual dumps are recommended.*
  55. * **Class Histogram Analysis**: Integrated analysis of heap objects (via `-XX:+PrintClassHistogram`).
  56. * **Flexible Filtering & Categorization**: Use custom filters and categories to manage large numbers of threads.
  57. * **AI Agent & MCP Support**: Headless analysis mode and standardized Agent Skill for integration with AI tools like Junie, Claude Code, OpenCode, Codex, and Pi.
  58. * **Session Management**: Save and reopen analysis sessions.
  59. ---
  60. ## 📦 Installation
  61. TDA can be installed or used in several ways:
  62. ### 1. Self-contained JAR
  63. The simplest way to use TDA is to download the `tda.jar` from the **Releases** page. Since it's a self-contained JAR, you can run it directly on any system with Java installed.
  64. ### 2. VisualVM Plugin
  65. TDA is available as a plugin for VisualVM. You can install it directly from the **VisualVM Plugin Center** (Tools -> Plugins).
  66. This integrates TDA's analysis capabilities directly into your VisualVM environment. The last available version in the plugin center is 2.4.
  67. For installing the recent version, download the three nbm files from the Releases page and install them manually in the VisualVM plugins settings.
  68. ### 3. macOS Binary (DMG)
  69. TDA provides a native macOS DMG package for easier installation. This package includes its own Java runtime, so no separate Java installation is required to run it.
  70. #### Installation (Unsigned Binary)
  71. Since the DMG is currently unsigned, macOS will block it by default with a warning that the "developer cannot be verified". To install and run TDA:
  72. 1. Download the `TDA-<version>.dmg` from the Releases page.
  73. 2. Open the DMG and drag **TDA.app** to your **Applications** folder.
  74. 3. **Right-click** (or Control-click) on `TDA.app` in your Applications folder and select **Open**.
  75. 4. A dialog will appear asking if you are sure you want to open it. Click **Open**.
  76. 5. After this first launch, you can open TDA normally from Launchpad or Spotlight.
  77. If this fails, you might need to confirm the installation from the system settings. For this just follow the instructions after clicking on the '?' Icon on the upper right corner of the error dialog.
  78. ---
  79. ## 🛠 Usage Modes
  80. TDA can be used in five different ways to suit your environment:
  81. ### 1. Standalone Application
  82. The most common way to use TDA for offline analysis of production log files. (See **[Installation](#1-self-contained-jar)** for how to get the JAR).
  83. **How to run:**
  84. ```bash
  85. java -Xmx512m -jar tda.jar
  86. ```
  87. Once opened, you can add log files containing thread dumps. TDA will parse them and display them in the tree view. If you
  88. have several or big log files, you might need to adjust the memory allocation by increasing the `-Xmx` flag.
  89. <div style="text-align: center;"><img src="./tda-main-screen.png" alt="TDA Main Screen" width="600"></div>
  90. #### Important Features:
  91. * **Thread Dump Tree**: Navigate through all detected dumps in a log file.
  92. * **Regular Expression for Timestamps**: Since thread dumps often lack timestamps, you can provide a regex to correlate dumps with log entries.
  93. * **Find Long Running Threads**: Compare consecutive dumps to see which threads haven't moved.
  94. * **Filters & Categories**: Group threads by name or state to reduce noise.
  95. * **Monitors & Deadlocks**: Detailed view of monitor usage and automatic deadlock detection.
  96. ### 2. JConsole Plugin
  97. Analyze a running application directly within JConsole. This is particularly useful for production environments where
  98. you need to quickly inspect the state of a live system. The plugin is part of the standalone jar, which needs to be downloaded for this.
  99. **How to use:**
  100. Start JConsole with the TDA plugin:
  101. ```bash
  102. jconsole -pluginpath tda.jar
  103. ```
  104. A new "Thread Dumps" tab will appear. From here, you can:
  105. * **Request Thread Dumps**: Generate fresh dumps directly from the connected JVM.
  106. * **Analyze in Real-time**: Use all of TDA's parsing and analysis features on the live data.
  107. ### 3. VisualVM Plugin
  108. TDA is also available as a plugin for VisualVM. You can install it directly from the **VisualVM Plugin Center**.
  109. It provides the same powerful analysis tools integrated into your VisualVM workflow. (See **[Installation](#2-visualvm-plugin)** for details).
  110. ### 4. JSON-based Thread Dumps (Experimental)
  111. Newer JDK versions allow generating thread dumps in JSON format using:
  112. ```bash
  113. jcmd <pid> Thread.dump_to_file -format=json <file>
  114. ```
  115. TDA can parse these files, but please note that the information provided in the JSON format is currently more basic than the traditional textual output. For example, it often lacks detailed thread states (like `MONITOR_WAIT` vs `WAITING`) or native thread IDs (`nid`).
  116. **Recommendation:** For in-depth analysis of deadlocks, monitor contention, or specific thread states, the **textual thread dump format is still preferred**.
  117. ### 5. AI Agent & MCP Integration (Headless Analysis)
  118. For integration with AI assistants (such as Junie, Claude Code, OpenCode, Codex, and Pi Agent) or automated pipelines,
  119. TDA can run headlessly via the **Model Context Protocol (MCP)** or as a standardized **Agent Skill**. This offloads computation
  120. and parsing to TDA, preventing agents from consuming token budgets and degrading context by ingesting raw multi-megabyte log files.
  121. There are two primary ways to integrate TDA into your AI workflow:
  122. #### Option 1: Agent Skill Configuration (Recommended)
  123. TDA provides a standardized **Agent Skill** (`tda-thread-dump-analysis`) conforming to the open [agentskills.io](https://agentskills.io) specification.
  124. ##### ✨ Benefits
  125. - **🛑 Strict Context Guardrails**: Instructs agents never to `cat` or read massive raw log files into context.
  126. - **📋 Structured Diagnostic Protocol**: Automatically sequences the investigation: `parse_log` ➔ `get_summary` ➔ `check_deadlocks` ➔ `analyze_virtual_threads` ➔ `find_long_running` ➔ `drill_down`.
  127. - **🔄 Dual-Mode Compatibility**: Supports agents with native MCP (Junie, Claude Code, OpenCode, Codex) as well as minimal/bash-centric agents like **Pi Agent** via a bundled CLI bridge (`scripts/tda_client.py`).
  128. ##### Skill Installation & Discovery
  129. - **Via Agent Skills Package Manager**:
  130. ```bash
  131. npx skills add https://github.com/irockel/tda
  132. ```
  133. - **Via Repository Symlink**:
  134. The skill is located canonically in `.agents/skills/tda-thread-dump-analysis/` and exposed via `skills/tda-thread-dump-analysis/`:
  135. - **Junie**: `.junie/skills/` or `.agents/skills/`
  136. - **OpenCode**: `.agents/skills/` or `.opencode/skills/`
  137. - **Claude Code**: `.claude/skills/` or `.agents/skills/`
  138. - **Codex**: `.agents/skills/`
  139. - **Herdr**: Shared workspace `.agents/skills/`
  140. ##### Standalone CLI Bridge for Pi Agent & Terminal Agents
  141. For agents without native MCP support (such as **Pi Agent** or CLI subagents):
  142. ```bash
  143. # Full end-to-end automated analysis report:
  144. python3 .agents/skills/tda-thread-dump-analysis/scripts/tda_client.py analyze /path/to/dump.log
  145. # Structured JSON output for agents:
  146. python3 .agents/skills/tda-thread-dump-analysis/scripts/tda_client.py analyze /path/to/dump.log --json
  147. # Specific diagnostic queries:
  148. python3 .agents/skills/tda-thread-dump-analysis/scripts/tda_client.py deadlocks /path/to/dump.log
  149. python3 .agents/skills/tda-thread-dump-analysis/scripts/tda_client.py virtual-threads /path/to/dump.log
  150. python3 .agents/skills/tda-thread-dump-analysis/scripts/tda_client.py long-running /path/to/dump.log
  151. ```
  152. ---
  153. #### Option 2: Direct MCP Server Integration
  154. If you prefer to configure TDA directly as a native MCP server in your agent or MCP client (e.g. Junie, Claude Desktop):
  155. ##### How to Run:
  156. ```bash
  157. java -Djava.awt.headless=true -jar tda.jar --mcp
  158. ```
  159. ##### Integration Example (e.g. Junie `mcp.json` or standard MCP client):
  160. ```json
  161. {
  162. "mcpServers": {
  163. "tda": {
  164. "command": "java",
  165. "args": ["-Djava.awt.headless=true", "-jar", "path/to/tda.jar", "--mcp"]
  166. }
  167. }
  168. }
  169. ```
  170. ##### Recommended System Prompt (Direct MCP Mode)
  171. When using direct MCP without the skill package, configure a system prompt (e.g. in `~/.junie/instructions.md` or your agent's system prompt) to prevent agents from dumping large files into context:
  172. ```markdown
  173. When you encounter a log file that appears to contain Java thread dumps:
  174. 1. DO NOT try to read or "cat" the entire file if it's large.
  175. 2. Use the `tda` MCP toolset.
  176. 3. First, call `parse_log(path="...")` to initialize the analysis.
  177. 4. Use `get_summary()`, `check_deadlocks()`, `find_long_running()`, `analyze_virtual_threads()`, `get_native_threads()`, and `get_zombie_threads()` to perform the analysis.
  178. 5. Provide your insights based on the structured data returned by these tools rather than the raw log text.
  179. ```
  180. ---
  181. #### Available MCP Tools
  182. The MCP server exposes the following tools (available both via direct MCP calls and via the CLI bridge):
  183. | Tool | Arguments | Description |
  184. |:--------------------|:--------------------------|:-----------------------------------------------------------------------------------------------|
  185. | `parse_log` | `path` (string, required) | Parses a log file containing Java thread dumps. This must be the first action for a log file. |
  186. | `get_summary` | None | Returns a summary of all parsed thread dumps (index, name, timestamp, thread/deadlock counts). |
  187. | `check_deadlocks` | None | Checks for and returns information about any deadlocks detected in the parsed thread dumps. |
  188. | `find_long_running` | None | Identifies threads that remain in the same state/stack trace across consecutive dumps. |
  189. | `analyze_virtual_threads` | None | Detects virtual threads where the carrier thread is stuck in application code. |
  190. | `get_native_threads` | `dump_index` (int, required) | Returns a list of all threads in a native method for a specific thread dump. |
  191. | `get_zombie_threads` | None | Returns a list of zombie threads (unresolved SMR addresses) with timestamps and dump names. |
  192. | `clear` | None | Resets the server state and clears the internal thread store for a new log file. |
  193. There is also an [article on dev.to](https://dev.to/irockel/stop-reading-raw-stacktraces-ai-powered-java-thread-dump-analysis-with-mcp-4673) about how to use TDA as an MCP server.
  194. 👉 **For complete configuration recipes across Junie, OpenCode, Claude Code, Codex, Pi, and Herdr, see the [Multi-Agent Integration Guide](docs/agent-integration.md).**
  195. 👉 **For JVM thread states, monitor locking graphs, and virtual thread pinning theory, see the [Diagnostics Reference Guide](.agents/skills/tda-thread-dump-analysis/references/diagnostics.md).**
  196. ---
  197. ## 🏗 Building from Source
  198. TDA is built using Maven. It requires **Java 11** or higher to build and run.
  199. ```bash
  200. mvn clean package
  201. ```
  202. This will build all components:
  203. * The standalone TDA JAR (in `tda/target/tda-x.x.jar`).
  204. * The VisualVM plugins as NBM files (in the `target/` directory of each `visualvm-*` module).
  205. To build the macOS DMG package, use the `release` profile (requires macOS and JDK 17+):
  206. ```bash
  207. mvn clean package -Prelease
  208. ```
  209. The resulting standalone JAR will also be located in the `tda/target/` directory.
  210. ---
  211. ## 🛠️ Troubleshooting
  212. If you encounter issues while using TDA, check the following sections for guidance.
  213. ### 1. Logging
  214. TDA maintains a centralized log file to help diagnose issues. If something isn't working as expected, the log file is the first place to look.
  215. #### Log File Locations
  216. * **macOS**: `~/Library/Logs/TDA/tda.log`
  217. * **Windows**: `%LOCALAPPDATA%\TDA\Logs\tda.log`
  218. * **Linux/Unix**: `~/.tda/logs/tda.log`
  219. #### Error Indicators (UI Mode)
  220. In standalone or plugin mode, TDA will display a **red dot** in the status bar (next to the memory indicator) if a critical error has occurred. Hover over the dot to see a tooltip reminding you to check the log file.
  221. ### 2. MCP Server Specifics
  222. Running TDA as a headless MCP server has specific requirements:
  223. * **Headless Environment**: Ensure you pass `-Djava.awt.headless=true` when running the JAR. TDA is a Swing-based application, and the MCP mode must bypass UI initialization.
  224. * **Std-in/Std-out Pollution**: The MCP protocol communicates via `stdin` and `stdout`. Avoid using any commands or scripts that print additional information to `stdout`, as this will corrupt the JSON-RPC stream and cause the AI client to lose connection.
  225. * **Absolute Paths**: When calling `parse_log`, always use **absolute paths** for the log file. The working directory of the MCP server might not be what you expect depending on how your AI client (e.g., Claude Desktop) launches it.
  226. * **Permissions**: Ensure the user running the AI client has read permissions for the log files being analyzed.
  227. ### 3. Memory Management
  228. Thread dumps from large production systems can be hundreds of megabytes.
  229. * **OutOfMemoryErrors**: If TDA crashes or fails to parse a large file, increase the heap size using the `-Xmx` flag:
  230. ```bash
  231. java -Xmx2g -jar tda.jar
  232. ```
  233. * **Max Logfile Size**: TDA has a safety limit for log file sizes. You can adjust this in the **Preferences** dialog (UI mode) or by manually editing the configuration if necessary.
  234. ---
  235. ## 📜 License
  236. TDA is licensed under the **Lesser GNU General Public License (LGPL)**.
  237. ---
  238. *For more detailed information, please refer to the source code. The wiki has been removed because it was outdated.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.