Skip to main content
Glama

jdx — an IDE for AI agents

Latest Release Linux CI macOS CI Windows CI Release CI License M8ven Score

Website & docs: mohammadmd1383.github.io/jdx

Try it in 30 seconds

curl -fsSL https://raw.githubusercontent.com/MohammadMD1383/jdx/main/install-release.sh | bash
jdx members java.util.HashMap --limit 5
# MCP (Claude Code / Cursor): {"mcpServers":{"jdx":{"command":"jdx","args":["mcp"]}}}
# MCP (OpenCode v1+v2): jdx setup --agent opencode --scope project   (then restart opencode)
# MCP (Claude Code): jdx setup --agent claude-code --scope project   (then restart claude)
# MCP (Cursor): jdx setup --agent cursor --scope project   (then restart Cursor)
# MCP (Kilo Code): jdx setup --agent kilo --scope project   (then restart Kilo Code)
# MCP (Cline): jdx setup --agent cline --scope system   (then restart Cline)
# MCP (Codex CLI): jdx setup --agent codex --scope project   (then restart codex)
# MCP (GitHub Copilot CLI): jdx setup --agent copilot --scope project   (then restart copilot)
# MCP (Antigravity): jdx setup --agent antigravity --scope project   (then restart Antigravity)
# MCP (Windsurf / Devin): jdx setup --agent windsurf --scope project   (then restart Windsurf)
# MCP (Aider / AiderDesk): jdx setup --agent aider --scope project   (then restart AiderDesk; core Aider has no MCP)

An AI agent working on a JVM codebase spends most of its time — and most of its context window — answering questions a human answers in an IDE with one keystroke:

What methods does this class have? What does this method actually do? Who calls it? What implements this interface?

Today an agent answers those with unzip, javap, grep, and by reading 1,400-line source files into its context. It is slow, noisy, and expensive, and javap gives it erased signatures and raw opcodes.

jdx answers them directly — from .jar, -sources.jar, class directories, source directories, Maven coordinates, and the JDK itself:

$ jdx members java.util.HashMap --limit 5
members of java.util.HashMap
constructors declared on java.util.HashMap:
  constructor public HashMap()
  constructor public HashMap(int initialCapacity)
  ...
5 of 54 members shown (--limit 54 to see more)
source: java.base (jrt)

$ jdx body 'java.util.HashMap#get(java.lang.Object)'
java.util.HashMap#get(java.lang.Object)
  source: decompiled by vineflower from java.base · java/util/HashMap.java:178-182  ⚠ reconstructed
   @Override
   public V get(Object key) {
      Node<K, V> e;
      return (e = this.getNode(key)) == null ? null : e.value;
   }

No sources jar? It decompiles with Vineflower — and says so, so the agent knows it is reading a reconstruction (pass --engine javap for raw opcodes instead).

Proof, not promises. One real task — list Gson's API, then show only toJson(Object) — measured on gson-2.14.0:

Approach

calls

bytes in context (~tokens)

unzip + javap + grep + sed

5

~17.5 KB (~4.4k) — and head -200 misses the method (line 542 of 1265)

jdx members + jdx body

2

~4.6 KB (~1.2k) — exact method, 267 bytes (~67 tokens)

The body alone: 267 bytes vs 60,590 (javap -c, 226×) vs 58,251 (full Gson.java, 218×). Tokens ≈ bytes/4. Reproduce it: sh docs/bench-compare.sh.

Same task, two agents — left does it with javap/grep, right with jdx:

baseline vs jdx: find all System.exit call sites in java.base

baseline vs jdx: show only the body of HashMap#get

baseline vs jdx: who implements java.util.Map

baseline vs jdx: inspect Gson from a Maven coordinate

Related MCP server: srclight

Install

Requires JDK 21+. Every push of a vX.Y.Z tag publishes per-OS bundles as GitHub Releases — jdx-<version>-<os>.tar.gz and jdx-<version>-<os>.zip (<os> is linux, macos, or windows), each with a .sha256 checksum and a jdx.jsa trained on that OS:

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/MohammadMD1383/jdx/main/install-release.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/MohammadMD1383/jdx/main/install-release.ps1 | iex

Linux/macOS installs per-user into ~/.local/share/jdx and links ~/.local/bin/jdx. Windows installs into %LOCALAPPDATA%\Programs\jdx and adds that directory to the user PATH (jdx.bat is the entry point). Verify with jdx version (jdx doctor reports JDK, cache, index, Kotlin sidecar, AppCDS archive, daemon, and workspace status). Release installs self-update with jdx upgrade. Building from source: ./gradlew :app:installDist && ./install.sh (POSIX) or gradlew.bat :app:installDist then .\install.ps1 (Windows) — see CONTRIBUTING.md.

Releases are unsigned: Windows SmartScreen and macOS Gatekeeper will warn on first run. Unblock-File jdx.bat (PowerShell) or xattr -d com.apple.quarantine <install-dir>/jdx clears it. Details and the asset table live in docs/PROPOSAL.md §17.2.

Quickstart

# No setup: the running JDK is always on the classpath via jrt:/
jdx members java.util.HashMap --inherited --limit 10
jdx body 'com.google.gson.Gson#toJson(Object)' --jars gson.jar

# Name a classpath once, reuse it everywhere (incl. daemon/MCP/HTTP/batch)
jdx ws create fx --jars 'libs/*.jar' --src ./src
jdx -w fx usages 'com.example.Service#run()'

# Maven coordinates resolve from ~/.gradle/caches + ~/.m2 first;
# --fetch downloads from Maven Central (with -sources.jar) when allowed
jdx show com.google.gson.Gson --coord com.google.code.gson:gson:2.14.0 --fetch

# Token budgets for the biggest listings (text only; --json bytes are unaffected)
jdx members java.util.HashMap --inherited --brief --max-lines 20

# Warm path: start once, query at ~20 ms instead of ~250 ms cold.
# The daemon never fetches — prime stored --coord jars once cold with --fetch
# (or use --jars) before `daemon start` / `mcp` / `serve`.
jdx daemon start -w fx
jdx -w fx members 'com.example.Service'   # served warm automatically

# One process, many queries
echo '{"command":"show","query":"java.util.Map"}' | jdx batch --jars gson.jar

# Upgrading a dependency? Ask what actually breaks
jdx diff gson-2.11.0.jar gson-2.14.0.jar --fail-on breaking

What makes it an IDE, not a better javap

  • Inherited members resolved transitively, with generic substitution — the agent never walks a class hierarchy by hand again.

  • A real index, so find usages, implementors, and call hierarchy work across an entire classpath, not just one jar.

  • Sources when they exist, decompilation when they don't — uniformly, behind one command.

  • True Kotlin signatures from @Metadata: suspend, properties, default arguments, @JvmName mappings — not the misleading JVM projection.

  • Javadoc/KDoc, including documentation inherited from a supertype.

  • jdx samples — real call sites from the classpath as usage examples. Evidence instead of recollection.

  • jdx literals — search string constants (LDC / ConstantValue) and .properties keys/values across a workspace for resource keys, log messages, and markers (issue #86). No more unzip | tr | grep.

  • jdx services — list META-INF/services SPI providers across a workspace (issue #25). Answer "who provides com.foo.Spi?" without unzipping jars.

  • jdx modules — list JPMS module-info descriptors (requires / exports / opens / uses / provides) across jars and the running JDK (issue #25).

  • jdx manifest — list META-INF/MANIFEST.MF attributes across a workspace (issue #25): main attributes by default (Main-Class, Multi-Release, …); --entries for per-entry (JarEntry) sections.

  • jdx resources — list non-class resource paths (META-INF/…, .properties, versioned META-INF/versions/… copies, …) across a workspace (issue #25); --cat prints the unique match's text (binary payloads refuse to dump bytes).

  • jdx diff a.jar b.jar — the public-API diff for a dependency upgrade, with every difference named as a rule (MEMBER_REMOVED, RETURN_TYPE_CHANGED, …) at breaking/suspicious/info, and a --fail-on gate for CI.

What makes it for agents, not for humans

  • Minimal correct output. Bounded, with an explicit hint for getting the rest. Never a file dump when a method was asked for.

  • Never guesses. An ambiguous reference exits 2 and lists every candidate as a copy-pasteable reference.

  • Machine-legible outcomes. Distinct exit codes for not found, ambiguous, no index, bad usage — branch without parsing prose. --json for everything.

  • Provenance on every answer — which jar, sources or bytecode, which decompiler.

  • jdx batch — many queries, one process, one index load.

  • Four front-ends over one engine: one-shot CLI, MCP server, a daemon, and a local HTTP/JSON API.

  • jdx help --agent — a compact paste-ready block for CLAUDE.md / system prompts.

Full command reference

The catalogue lives in docs/COMMANDS.md — every command, flag, exit code, and the symbol-reference grammar. jdx <command> --help documents each command; jdx help --agent prints the compact agent block.

Known limitations (by design)

Graph queries re-scan live bytecode roots per query (no persistent-index acceleration yet). callers is override-aware by default (--exact for invoke-owner matching); calls stays bytecode-exact. Full list in GitHub Issues. Out-of-scope for v1 (mappings/remap, …) is the phase-2 backlog, also tracked there. To inspect a Minecraft jar, pass the mapped jar your toolchain already produced — see Inspect Minecraft mod jars.

Documentation

Website

Guides, generated command and MCP reference, integrations, FAQ

docs/guide/

User guides: install, quickstart, AI agents, classpath, reading and navigating code, API diff, Minecraft mod jars

docs/COMMANDS.md

Full command reference (flags, exit codes, symbol grammar)

AGENTS.md (+ per-module AGENTS.md)

Contributor notes: architecture rules, gotchas, build/test

docs/PROPOSAL.md

Full design specification (Appendix B is the flag reference)

docs/TESTING.md

Testing strategy — required reading before writing tests

CONTRIBUTING.md

Conventions, code style, definition of done

GitHub Issues

Limitations, caveats, and the phase-2 backlog

Contributing

Contributors here — human and AI — do not share memory. Read CONTRIBUTING.md before your first change; it is short and it explains the documentation discipline that keeps the project resumable by anyone.

License

Apache-2.0 (see LICENSE). Bundled third-party components and their licenses are listed in docs/PROPOSAL.md §19 and will be reproduced in NOTICE.

Available Tools

27 tools
jdx_annotatedA

List classes/members carrying an annotation (issue #26). Query may be a type, '@Type(k=v)' use spelling, or a recipe alias (deprecated|forRemoval|test|junit5|junit4|bean). Equivalent to usages with kind=annotation.

Inputs: query (required), in, limit, where, +3 more.

jdx_bodyB

Open the method: the source body of one member, sliced verbatim with provenance.

Inputs: query (required), engine, context, withDoc, +4 more.

jdx_callersA

Call hierarchy in: who calls this method, as a depth-bounded tree. Override-aware by default; set exact=true for invoke-owner matching only.

Inputs: query (required), in, depth, exact, +3 more.

jdx_callsC

Call hierarchy out: what this method calls, as a depth-bounded tree.

Inputs: query (required), in, depth, limit, +3 more.

jdx_diffA

What changed between two artifacts? Public-API diff with named binary-compatibility rules (MEMBER_REMOVED, RETURN_TYPE_CHANGED, ...), most breaking first. query is the OLD artifact and new the candidate; each is a jar, class dir, glob, or Maven coordinate. Exits 0 whenever the comparison ran.

Inputs: new (required), query (required), limit, failOn, +4 more.

jdx_docB

Quick documentation for a type or member, falling back to the nearest documenting supertype like IntelliJ quick-doc.

Inputs: query (required), raw, maxLines, inherited, +2 more.

jdx_doctorA

Environment report. The server refuses this over MCP — it describes the server's machine, not the client's — run jdx doctor in a shell instead.

Inputs: query, workspace.

jdx_healthB

Liveness probe: uptime, workspace served and queries answered.

Inputs: query, workspace.

jdx_hierarchyC

Type hierarchy: supertypes upward and subtypes downward across the workspace.

Inputs: query (required), in, up, down, +5 more.

jdx_implementorsB

Who implements this interface or extends this class, transitively.

Inputs: query (required), in, depth, limit, +3 more.

jdx_literalsB

Search string constants across bytecode roots (LDC loads and String field ConstantValue) and .properties resource keys/values. Substring by default; set regex=true for a Java regex.

Inputs: query (required), in, limit, regex, +3 more.

jdx_lsC

External library browser: packages in the workspace roots.

Inputs: limit, query, workspace.

jdx_manifestA

List META-INF/MANIFEST.MF attributes across the workspace jars. Default: main-section attributes. Set entries=true for per-entry (JarEntry) attributes instead. Omit query to list every attribute in that section; with a query, match the attribute name or value (and entry path when entries=true). Does not extract resource file bytes (use jdx_resources with cat=true for text).

Inputs: in, limit, query, regex, +4 more.

jdx_membersA

List the members of a type — the '.' completion equivalent. Inherited members are included by default, grouped by declaring type.

Inputs: query (required), from, grep, kind, +10 more.

jdx_modulesA

List JPMS module-info descriptors across the workspace (requires, exports, opens, uses, provides). Omit query to list every module; with a query, match the module name, an exported/opened package, a uses/provides service, or a provider class. Does not read META-INF/MANIFEST.MF attributes (use jdx_manifest for that).

Inputs: in, limit, query, regex, +3 more.

jdx_outlineC

File Structure: one dense line per member declared on a type (never inherited).

Inputs: query (required), from, grep, kind, +9 more.

jdx_resolveB

What is this symbol? Short-name resolution with copy-pasteable candidates.

Inputs: query (required), limit, workspace.

jdx_resourcesA

List non-class resource paths across the workspace jars (META-INF, .properties, versioned META-INF/versions/… copies, …). Omit query to list every resource; with a query, match the entry path. Pass cat=true to print the unique match's text contents (binary payloads refuse to dump bytes; ambiguous matches exit 2). maxLines caps --cat text lines (default 200).

Inputs: in, cat, limit, query, +5 more.

jdx_samplesB

How is this symbol really used? Ranked call sites with source snippets as evidence.

Inputs: query (required), in, limit, exclude, +3 more.

jdx_servicesA

List META-INF/services SPI registrations across the workspace jars. Omit query to list every registration; with a query, match the service interface FQN or a provider class FQN. Does not read module-info provides (use jdx_modules for that).

Inputs: in, limit, query, regex, +3 more.

jdx_showB

Go to declaration: the class card for a type (kind, supertypes, source, provenance).

Inputs: query (required), workspace.

jdx_signatureC

Parameter info: one signature line per overload, with real parameter names.

Inputs: query (required), view, limit, workspace, +1 more.

jdx_sourceC

Open the file: whole source for a type, or a slice of it, with provenance.

Inputs: query (required), lines, around, engine, +4 more.

jdx_treeC

External library browser: artifacts and their package trees.

Inputs: depth, limit, query, counts, +1 more.

jdx_usagesB

Find usages of a type or member across the workspace jars and source dirs. With kind=annotation, query may use annotation-use spelling '@Type(k=v)' (issue #26).

Inputs: query (required), in, kind, limit, +4 more.

jdx_versionB

The jdx version this server was built as.

Inputs: query, workspace.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 27 tools

    Disambiguation3/5

    Most tools have a clearly stated niche, and descriptions proactively cross-reference siblings (e.g. services vs modules vs manifest each name the tool to use instead). However there are real overlaps: jdx_annotated is explicitly 'equivalent to usages with kind=annotation', jdx_hierarchy's downward direction largely duplicates jdx_implementors, jdx_members vs jdx_outline differ only by inheritance handling, and jdx_ls vs jdx_tree both open with 'External library browser'. An agent can recover from the rich descriptions, but misselection is likely in those pairs.

    Naming Consistency5/5

    Every tool uses the identical `jdx_` prefix plus a single lowercase token (tree, resolve, members, callers, diff...), with no camelCase or separator drift anywhere. The verb/noun mix is intentional and readable (verbs like resolve/search/show/diff, nouns like members/hierarchy), so the convention is fully predictable.

    Tool Count3/5

    27 tools exceeds the comfortable range, and a few don't earn their place: jdx_doctor is explicitly non-functional over MCP, and jdx_version/jdx_health are thin meta probes. The remaining surface is broad but genuinely differentiated across navigation, relationships, and bytecode/artifact inspection, so it's heavy rather than bloated.

    Completeness4/5

    For a read-only JVM code-intelligence server the lifecycle is well covered: symbol search, short-name resolution, declarations, members, bodies, source slices, signatures, docs, usages, hierarchy, call graphs, samples, literals, SPI/JPMS/manifest/resource scanning, and artifact diffing. Gaps are minor for the stated purpose (no type-of-expression or diagnostics/compile-check operation), and read-only operation means no write tools are expected.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables AI tools to analyze Java dependencies by scanning Maven projects, decompiling JAR files, and extracting detailed class information including methods, fields, and inheritance relationships. Solves the problem of AI hallucinations when generating code that calls external dependencies by providing accurate class structures through decompilation.
      3
      21 npm
      42
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Deep code indexing for AI agents. Search symbols, navigate call graphs, explore inheritance, track git history — all via MCP.
      76 PyPI
      59
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Indexes local Maven and Gradle caches to enable AI agents to search for Java classes, method signatures, and source code, including from internal or obscure libraries.
      24
      ISC