agentleFS
eduardoghieduardoghi/reverse-engineering-skills/skills/java-decompile/SKILL.md

java-decompile

Skill2 starsChanged 12 days agoMITView on GitHub

Decompile Java JAR and .class files to readable source with Vineflower, using CFR as a second opinion and javap bytecode as the tie-breaker. Use when you need to know how methods in a JAR are implemented, compare two versions of a JAR, or find SQL, URLs and constants inside Java code. Prefer it over javap alone for anything beyond signatures.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. quarkusio/quarkusdev-skills★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository8 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 4 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run java-decompile --check if any of them seems to be missing.

    line 13
  2. Very specific:

    Get a second opinion from CFR: when a method looks wrong: missing bodies, <unknown> types, tangled control flow, or a comment saying it …

    line 41
  3. Distinctive:

    Confirm in the bytecode: when a conclusion depends on a branch, a constant, the exact method called or the order of operations, and always …

    line 49
  4. Very specific:

    Every output directory it creates, or finds empty and starts using, gets a .java-decompile-output marker file.

    line 85
  5. Distinctive:

    When the input is a directory of classes, the output can't be the same directory or inside it.

    line 92
  6. Very specific:

    If --only fails or finds nothing in a JAR (Vineflower 1.12.0 crashes with NoSuchFileException on classes under BOOT-INF/classes/), it …

    line 95
  7. Distinctive:

    Use separate, new output directories for each version.

    line 106
  8. Very specific:

    Check META-INF/maven/*/*/pom.properties in both for version bumps of the product and its libraries.

    line 119
  9. Distinctive:

    Keep decompiled output out of git repositories.

    line 129

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Java decompilation

Decompiled code is a reconstruction, not the original source. Local variable names, loop shapes and if/else order may differ from what was written, and some methods come out wrong. Treat it as a strong lead and confirm anything important in the bytecode.

Tools: java-decompile (wraps Vineflower, from this repo's bin/), cfr, and javap/jar from the JDK. Run java-decompile --check if any of them seems to be missing.

Method

  1. Look at the layout first.

    jar tf app.jar | sed 's#/[^/]*$##' | sort | uniq -c | sort -rn | head -30

    Find the vendor's own packages and note whether they sit at the root, under BOOT-INF/classes/ (Spring Boot) or under WEB-INF/classes/ (WAR). Nested JARs under BOOT-INF/lib/ or WEB-INF/lib/ are separate inputs: extract the one you need and decompile it on its own. META-INF/maven/*/*/pom.properties gives the product version and the bundled libraries.

  2. Check for real source. A *-sources.jar next to the binary, a public repository for the version in pom.properties, or source files inside the JAR beat any decompiler. Use them when they exist.
  3. Decompile with Vineflower, limited to the vendor package. --only takes the slash-separated class name (com/vendor/product), without any BOOT-INF/classes/ prefix:

    java-decompile --only=com/vendor/product app.jar /tmp/app-src

    Vineflower still copies every non-class resource in the JAR (.properties, .xml, .txt) into the output. Only the .java files under the prefix are decompiled.

  4. Get a second opinion from CFR when a method looks wrong: missing bodies, <unknown> types, tangled control flow, or a comment saying it couldn't be decompiled. --jarfilter is a regex over dotted class names:

    cfr app.jar --outputdir /tmp/app-src-cfr --jarfilter '^com\.vendor\.product\.Foo$'
  5. Confirm in the bytecode when a conclusion depends on a branch, a constant, the exact method called or the order of operations, and always when Vineflower and CFR disagree:

    javap -c -p -v -cp app.jar com.vendor.product.Foo

    For classes under BOOT-INF/classes/, extract them first (unzip app.jar 'BOOT-INF/classes/*' -d /tmp/x) and use -cp /tmp/x/BOOT-INF/classes. The bytecode decides.

javap -p alone is fine for a quick look at signatures and javap -v for the constant pool. Don't stop there when you need to know what a method does.

Shell tips

  • Print one method from the bytecode instead of the whole class. The range ends at the blank line after the method, after its exception table:

    javap -c -p -cp app.jar com.vendor.product.Foo | awk '/ methodName\(/,/^$/'
  • Signed JARs list a digest for every entry in MANIFEST.MF, which can be tens of thousands of lines. Print only the main section. The file uses CRLF, hence the \r:

    unzip -p app.jar META-INF/MANIFEST.MF | sed '/^\r\?$/q'
  • grep treats .class files as binary and lists nothing for -l. Add -a to search strings in extracted classes (grep -rla 'X-Api-Key' classes/).

java-decompile behaviour

  • Without an output directory it creates a new ${TMPDIR:-/tmp}/<jar name>-src.XXXXXX with mktemp and prints the final path. Read the path from the output instead of guessing it.
  • Every output directory it creates, or finds empty and starts using, gets a .java-decompile-output marker file.
  • A non-empty output directory is refused. --clean empties it (keeping the directory) only if it has the marker. Any other non-empty folder is never cleaned. Delete it by hand if you really want to reuse it.
  • --clean accepts a marked directory even if it was used for another input, since it empties it first. For version comparisons, still use one directory per version.
  • When the input is a directory of classes, the output can't be the same directory or inside it.
  • An output path that is a symlink, a regular file or a directory owned by another user is refused, and so are /, $HOME and the current directory.
  • If --only fails or finds nothing in a JAR (Vineflower 1.12.0 crashes with NoSuchFileException on classes under BOOT-INF/classes/), it extracts the matching classes from the root, BOOT-INF/classes/ and WEB-INF/classes/ into a temporary directory and decompiles them from there. The output paths are the same as a direct run.
  • Extra Vineflower options go after --, e.g. java-decompile app.jar out -- --thread-count=4. The script passes them before --only, because Vineflower 1.12.0 treats anything after --only= as an input path and ignores it with warn: missing '...'. Keep that order if you call Vineflower directly.
  • A full decompile of a 15 MB fat JAR takes minutes. Use --only whenever you know the package.

Comparing two versions of a JAR

  1. Use separate, new output directories for each version. Never decompile the second version into the first one's directory.
  2. Compare the class lists before decompiling anything:

    jar tf old.jar | grep '\.class$' | sort > old.txt
    jar tf new.jar | grep '\.class$' | sort > new.txt
    diff old.txt new.txt
  3. Find the classes that changed by hashing the .class files (unzip both, then sha256sum per file and join on the path). Bytecode can change with the same source when the compiler or build changes, so a different hash means "look at it", not "the logic changed".
  4. Check META-INF/maven/*/*/pom.properties in both for version bumps of the product and its libraries.
  5. Decompile only the changed vendor classes, with the same tool and options on both sides, and diff -ru old-src new-src.
  6. Ignore differences that are only formatting, renamed local variables (var1 vs var2), or reordered synthetic members (lambda$foo$3, access$000, bridge methods). Their names and numbering shift when unrelated code moves.
  7. For quick triage, javap -p signatures and the string constants from javap -v often show the change (new SQL, new endpoint, new parameter name) before you read any method.
  8. Confirm each change you report in the bytecode of both versions.

Keep decompiled output out of git repositories.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.