Skip to main content
Glama
README.md
# `jdx` — an IDE for AI agents

[![Latest Release](https://img.shields.io/github/v/release/MohammadMD1383/jdx)](https://github.com/MohammadMD1383/jdx/releases)
[![Linux CI](https://github.com/MohammadMD1383/jdx/actions/workflows/linux.yml/badge.svg)](https://github.com/MohammadMD1383/jdx/actions/workflows/linux.yml)
[![macOS CI](https://github.com/MohammadMD1383/jdx/actions/workflows/macos.yml/badge.svg)](https://github.com/MohammadMD1383/jdx/actions/workflows/macos.yml)
[![Windows CI](https://github.com/MohammadMD1383/jdx/actions/workflows/windows.yml/badge.svg)](https://github.com/MohammadMD1383/jdx/actions/workflows/windows.yml)
[![Release CI](https://github.com/MohammadMD1383/jdx/actions/workflows/release.yml/badge.svg)](https://github.com/MohammadMD1383/jdx/actions/workflows/release.yml)
[![License](https://img.shields.io/github/license/MohammadMD1383/jdx)](LICENSE)
[![M8ven Score](https://m8ven.ai/badge/mcp/mohammadmd1383/jdx)](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`:

![baseline vs jdx: find all System.exit call sites in java.base](docs/demo-callsites.gif)

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

![baseline vs jdx: show only the body of HashMap#get](docs/demo-method-body.gif)

![baseline vs jdx: who implements java.util.Map](docs/demo-implementors.gif)

![baseline vs jdx: inspect Gson from a Maven coordinate](docs/demo-maven-deps.gif)

</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

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