maven-code-graph

The AI coding bottleneck isn't the AI — it's that the AI can't see your dependencies.

Give your AI coding assistant eyes into your Maven dependencies. It indexes every JAR in your pom.xml so the AI can read any dependency's method signatures, parameter names, and Javadoc in 0.2s — like Ctrl+Click in an IDE.

中文版 · Documentation

The Problem

Your AI is writing code and needs to call an external library:

// AI is writing OrderService.java
public List<OrderItemDTO> getOrderItems(Long orderId) {
    return paymentService.getOrderItems(orderId, ???);  // ← what's the second parameter?
}

paymentService comes from an external dependency payment-api, not in the project source. The AI can't see the method signature, so it either stops or guesses a type — and the build breaks.

If you're in an IDE, Ctrl+Click solves it instantly. But AI doesn't have an IDE. Its only option is:

grep -rn "PaymentService"   →  find the import
grep -A2 "payment-api" pom.xml  →  guess the artifact coordinate
find ~/.m2/.../payment-api  →  locate the JAR
unzip -p ...sources.jar ...PaymentService.java  →  extract source
# 30+ seconds later: Result<List<OrderItemDTO>> getOrderItems(Long, String)
# Parameter names lost, no Javadoc

Even that's the best case. Worse: package names and artifact coordinates have no reliable mapping. com.example.payment.core might come from payment-api, or core-lib, or anything else. The AI has to guess from dozens of pom.xml entries or scan 2000+ JARs in ~/.m2.

The AI coding bottleneck isn't the AI — it's that the AI can't see your dependencies.

What It Does

# Search for a class
$ maven-code-graph search PaymentService
com.example.payment.core.PaymentService  [interface]
  com.example:payment-api:2.3.1

# See full method signatures
$ maven-code-graph class com.example.payment.core.PaymentService

public interface PaymentService {
  Result<List<OrderItemDTO>> getOrderItems(Long orderId, String credential);
  Result<PaymentDTO> getPaymentById(Long paymentId, PaymentQueryParam param);
  ...
}

# Full source with Javadoc
$ maven-code-graph class com.example.payment.core.PaymentService --type source

# Just the Javadoc
$ maven-code-graph class com.example.payment.core.PaymentService --type docs

# Find implementations
$ maven-code-graph implementations com.example.payment.core.PaymentService

The AI goes from import statement to complete method signatures in 0.2 seconds.

Tip: The CLI is also available as the shorter alias mcg — mcg search PaymentService, mcg class ....

Prerequisites

• Node.js >= 18 — required to run the CLI
• Maven (mvn) — required for dependency resolution; must be available on PATH
• JDK 21+ — only needed for Fernflower decompilation, when a dependency JAR doesn't ship with -sources.jar. If you have IntelliJ IDEA installed, its bundled JDK is auto-detected

Install

npm install -g maven-code-graph
npx skills add auver/maven-code-graph

First command installs the CLI, second registers the AI skill.

How It Works

maven-code-graph init (first run)
  → reads pom.xml → mvn dependency:build-classpath → gets all JAR paths
  → Most JARs ship with -sources.jar → tree-sitter-java parses source → extracts classes/methods/inheritance
  → 5% have no source → Fernflower decompiles → tree-sitter-java parses
  → stores everything in SQLite (~/.maven-codegraph/artifacts.db)

Every AI lookup
  → checks .maven-codegraph/state.json for pom.xml changes
  → FTS5 full-text search → millisecond response
  → prefers sources.jar, then cached decompiled output, falls back to javap

The index is shared globally — the same JAR used by multiple projects is only parsed once.

With vs. Without

Without maven-code-graph, the AI's actual path:
  → grep import → grep pom.xml guess artifact → find .m2 locate JAR → unzip -p extract
  → parameter names lost, no Javadoc
  → 30+ seconds, breaks coding flow, version may be wrong

With maven-code-graph:
  → import gives the fully qualified name → maven-code-graph class com.example.PaymentService --type source
  → 0.2 seconds, complete source: parameter names, Javadoc, return types

maven-code-graph search is for exploratory browsing. For coding, the import statement IS the exact class name — just like Ctrl+Click in an IDE.

Decompilation (Fernflower)

Many Maven dependencies ship with -sources.jar, no decompilation needed. For those that don't, maven-code-graph uses Fernflower automatically.

Fernflower requires JDK 21+. maven-code-graph auto-detects in this order:

1. FERNFLOWER_JAVA env variable
2. IntelliJ IDEA's bundled JBR (if installed)
3. System java (if JDK 21+)

Most developers already have IDEA installed — it works out of the box.

FAQ

Q: Do I need IntelliJ IDEA? A: No. Most dependencies have -sources.jar already. Those that don't need Fernflower (JDK 21+), which auto-detects IDEA's bundled JDK if you have it.

Q: How long does the first index take? A: ~2-3 minutes for a typical project. Subsequent runs skip unless pom.xml changes.

Q: What if a dependency JAR has no source? A: The class is skipped during indexing. Lookups fall back to javap method signatures.

What It Means for AI Coding

maven-code-graph isn't a tool for humans — IDEs already solved that. It's infrastructure for AI coding assistants, filling the gap they hit when doing backend work: the AI isn't dumb, it just can't see your dependency code.

Think of it as the mirror image of codegraph — codegraph lets the AI read your project source, maven-code-graph lets the AI read your project dependencies.

Links

• 中文文档
• Architecture & Internals
• npm package

MIT License.