jdx
# `jdx` — an IDE for AI agents
[](https://github.com/MohammadMD1383/jdx/releases)
[](https://github.com/MohammadMD1383/jdx/actions/workflows/linux.yml)
[](https://github.com/MohammadMD1383/jdx/actions/workflows/macos.yml)
[](https://github.com/MohammadMD1383/jdx/actions/workflows/windows.yml)
[](https://github.com/MohammadMD1383/jdx/actions/workflows/release.yml)
[](LICENSE)
[](https://m8ven.ai/mcp/mohammadmd1383/jdx)
**Website & docs: [mohammadmd1383.github.io/jdx](https://mohammadmd1383.github.io/jdx/)**
## Try it in 30 seconds
```bash
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:
```console
$ 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`:

<details>
<summary>More side-by-side demos (method body · implementors · Maven coordinates)</summary>



</details>
## Install
Requires **JDK 21+**. Every push of a `vX.Y.Z` tag publishes per-OS bundles as
[GitHub Releases](https://github.com/MohammadMD1383/jdx/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:
```bash
# 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`](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
```bash
# 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`](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](https://github.com/MohammadMD1383/jdx/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](docs/guide/minecraft-mods.md).
## Documentation
| | |
|---|---|
| [Website](https://mohammadmd1383.github.io/jdx/) | Guides, generated command and MCP reference, integrations, FAQ |
| [`docs/guide/`](docs/guide/introduction.md) | User guides: install, quickstart, AI agents, classpath, reading and navigating code, API diff, Minecraft mod jars |
| [`docs/COMMANDS.md`](docs/COMMANDS.md) | Full command reference (flags, exit codes, symbol grammar) |
| [`AGENTS.md`](AGENTS.md) (+ per-module `AGENTS.md`) | Contributor notes: architecture rules, gotchas, build/test |
| [`docs/PROPOSAL.md`](docs/PROPOSAL.md) | Full design specification (Appendix B is the flag reference) |
| [`docs/TESTING.md`](docs/TESTING.md) | Testing strategy — required reading before writing tests |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Conventions, code style, definition of done |
| [GitHub Issues](https://github.com/MohammadMD1383/jdx/issues) | Limitations, caveats, and the phase-2 backlog |
## Contributing
Contributors here — human and AI — do not share memory. Read
[`CONTRIBUTING.md`](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`.
TDQS
Scored across 27 tools
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.
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.
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.
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.