quarkusio/quarkusdev-skills/java-classpath-search

Java Classpath Search

Fast search across all Maven dependencies to find which JARs contain a Java class.

Overview

This skill searches a pre-built index of all classes in your Maven local repository, providing instant results for classpath queries. It's essential for resolving imports, debugging classpath conflicts, and discovering dependency sources.

When to Use

• Finding which dependency provides a class
• Resolving "class not found" errors
• Checking for version conflicts (multiple JARs with same class)
• Discovering available implementations of an interface
• Understanding your project's dependency tree
• Verifying a dependency is in your local Maven repo

Quick Reference

Search patterns:

• Fully qualified: com.fasterxml.jackson.databind.ObjectMapper
• Simple name: ObjectMapper
• Partial pattern: jackson.ObjectMapper

Index location: $HOME/.cache/quarkusdev-skills/class-index.txt

Index refresh: Automatic if missing or older than 7 days

Implementation

Step 1: Determine Search Pattern

Parse the user input (available as $ARGUMENTS):

Step 2: Ensure Index is Available

The class index is a tab-separated file mapping class paths to JAR paths.

INDEX="$HOME/.cache/quarkusdev-skills/class-index.txt"
 
# Check if index needs rebuilding (missing or older than 7 days)
if [ ! -f "$INDEX" ] || [ $(find "$INDEX" -mtime +7 2>/dev/null | wc -l) -gt 0 ]; then
  # Dispatch index rebuild as subagent (can take 30-60 seconds)
  # Use Agent tool with prompt:
  # "Run the build-class-index.sh script from this skill directory
  #  Report when indexing is complete."
 
  # Wait for subagent to complete before continuing
fi

Note: Index building is dispatched to a subagent to keep the main conversation responsive. The script uses 8 parallel workers and typically completes in under 60 seconds.

Step 3: Search the Index

Search is instant (just grep on a text file):

For fully qualified class name:

grep "com/fasterxml/jackson/databind/ObjectMapper\.class" "$INDEX"

For simple class name:

grep -i "/ObjectMapper\.class" "$INDEX"

For partial pattern:

grep -i "jackson.*ObjectMapper\.class" "$INDEX"

Step 4: Check Local Build Output

Also search project build directories for classes:

find . -path "*/target/classes/*ClassName.class" 2>/dev/null

Step 5: Present Results

Format output to show:

1. Class path within JAR - The full package path
2. JAR file path - Highlight groupId, artifactId, version from path
3. Maven coordinates - Extract from JAR path:

`` ~/.m2/repository/com/fasterxml/jackson/core/jackson-databind/2.15.0/jackson-databind-2.15.0.jar ` Becomes: com.fasterxml.jackson.core:jackson-databind:2.15.0`

1. Conflict warnings - If multiple versions exist, flag as potential classpath issue

Example output format:

Found in 2 locations:
 
1. com/fasterxml/jackson/databind/ObjectMapper.class
   JAR: com.fasterxml.jackson.core:jackson-databind:2.15.0
   Path: ~/.m2/repository/com/fasterxml/jackson/core/jackson-databind/2.15.0/jackson-databind-2.15.0.jar
 
2. com/fasterxml/jackson/databind/ObjectMapper.class
   JAR: com.fasterxml.jackson.core:jackson-databind:2.14.2
   Path: ~/.m2/repository/com/fasterxml/jackson/core/jackson-databind/2.14.2/jackson-databind-2.14.2.jar
 
⚠️  WARNING: Multiple versions detected - potential classpath conflict

Step 6: Handle No Results

If search returns nothing:

1. Rebuild index - Run the build-class-index.sh script from this skill directory
2. Check spelling - Suggest corrected class name
3. Verify dependency - Class might not be in local repo, suggest mvn dependency:resolve
4. Broaden search - Try searching for just the class name without package

Index Details

What's indexed:

• All .class files in ~/.m2/repository/**/*.jar
• Excludes: -sources.jar, -javadoc.jar, -tests.jar, -test-*.jar
• Excludes: Inner classes ($), module-info, package-info

Index format:

com/example/MyClass.class\t/path/to/artifact-1.0.0.jar

Build time: ~30-60 seconds with 8 parallel workers

Size: Varies by repository size (typically 5-20 MB)

Tips

• Index is automatically refreshed every 7 days
• For inner classes, search JAR directly: jar tf /path/to.jar | grep ClassName
• Use -i flag for case-insensitive searches
• The index uses 8 parallel workers for fast building
• Subagent dispatch keeps main conversation responsive during index builds

Supporting Tool

The index is built by build-class-index.sh (included in this skill directory):

#!/bin/bash
INDEX_FILE="${1:-$HOME/.cache/quarkusdev-skills/class-index.txt}"
REPO_DIR="${2:-$HOME/.m2/repository}"
 
find "$REPO_DIR" -name "*.jar" \
  -not -name "*-sources*" \
  -not -name "*-javadoc*" \
  -not -name "*-tests*" \
  -not -name "*-test-*" | \
  xargs -P 8 -I{} sh -c '
    jar tf "$1" 2>/dev/null | grep "\.class$" | grep -v "module-info\|package-info" | while read cls; do
      printf "%s\t%s\n" "$cls" "$1"
    done
  ' _ {} > "$INDEX_FILE"

Platform Notes

This skill works with:

• Claude Code: Direct execution via Bash/Agent tools
• Gemini CLI: Use equivalent bash/file tools
• Codex: Use RunBash/SubAgent equivalents

The build-class-index.sh script is platform-independent (standard bash).