jade

# Jade — Just Agentic Development Environment

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="logo-dark.png">
  <img src="logo.png" alt="Jade — Just Agentic Development Environment" width="520">
</picture>

[![julianbei/jade MCP server](https://glama.ai/mcp/servers/julianbei/jade/badges/score.svg)](https://glama.ai/mcp/servers/julianbei/jade)

## The IDE for agents

Jade gives coding agents what an IDE gives you, served over MCP. Read by symbol,
edit against a known revision, get the compiler's diagnostics back with the
edit, validate with the repository's own commands, see what changed, and
revert to a checkpoint — each step one tool call, none of it through the shell.

Symbol-aware reading is how Jade finds its way around; the transaction is what
it is for. Where the shell is still the better tool, use it — the question
Jade has to answer is whether an agent gets more done, at acceptable cost,
with it than without ([docs/benchmark.md](docs/benchmark.md)).

**Half the tokens, more issues fixed.** Claude Code on 12 real closed issues
from cobra (Go), ky (TypeScript), requests (Python) and ripgrep (Rust), judged
by each upstream fix's own hidden tests:

| Claude Code with… | Issues fixed | Tokens per task | Time per task |
|---|---|---|---|
| its built-in tools | 10 of 12 | 1.38M | 215s |
| **Jade in their place** | **12 of 12** | **0.68M (−51%)** | **163s (−24%)** |

Not just a shorter tool list: against a shell trimmed to Bash, Read, Edit and
Write, Jade still used 18–25% fewer tokens and fewer turns, in two separate
runs. Sonnet 5, one run per task, four languages —
[results and caveats](docs/benchmark-results.md) ·
[how to set it up](#let-jade-replace-the-built-in-tools).

**Status:** 0.0.11 — early, usable, and looking for feedback. **Testing it?**
Start with [the tester guide](#trying-jade-a-guide-for-testers).

```bash
curl -fsSL https://raw.githubusercontent.com/julianbei/jade/main/install.sh | sh
```

For macOS and Linux — Windows isn't supported ([here's why, and where to upvote](https://github.com/julianbei/jade/issues/2)).
Run it again to update. [Other ways to install](#other-ways-to-install).

---

## Table of contents

- [Trying Jade: a guide for testers](#trying-jade-a-guide-for-testers)
- [Why Jade exists](#why-jade-exists)
- [Install](#install)
- [Configure your MCP client](#configure-your-mcp-client)
- [Use it in a container](#use-it-in-a-container)
- [The tools](#the-tools)
- [Repository commands](#repository-commands)
- [Language support](#language-support)
- [Design principles](#design-principles)
- [When the shell is still the right tool](#when-the-shell-is-still-the-right-tool)
- [What Jade does not do yet](#what-jade-does-not-do-yet)
- [Stability and versioning](#stability-and-versioning)
- [Telemetry](#telemetry)
- [Reporting problems](#reporting-problems)
- [Development](#development)

---

## Trying Jade: a guide for testers

Thanks for testing. Half an hour gets you set up; the useful part is a week or
two of your normal work with it switched on, and then telling us how it went —
**including if you turned it off.**

### 1. Install Jade and your language servers

**macOS and Linux:**

```bash
curl -fsSL https://raw.githubusercontent.com/julianbei/jade/main/install.sh | sh
```

**Windows** isn't supported, sorry! If you'd like it to be, please 👍
[issue #2](https://github.com/julianbei/jade/issues/2) or tell us there why it
matters to you. (WSL 2 runs Linux, so the Linux build may work there, but we
don't test it or take bug reports for it.)

The script picks the build for your OS and CPU, checks it against the
release's checksums and installs it to `/usr/local/bin`, or `~/.local/bin`
when that is not writable — no sudo, no Go toolchain. If that directory is
not on `PATH`, it offers to add it to your shell profile, and it prints the
absolute path to use as `command` in your MCP client config. On a first install it then opens
`jade-mcp install`, a menu that installs the language servers you pick, or
shows how to install them by hand; Enter skips it, and you can run it again
any time. **Run the same command again to
update** — Jade tells you when a new release is out (see
[Update check](#update-check)). (Prefer Go? `go install
github.com/julianbei/jade/cmd/jade-mcp@v0.0.11` works too.) Jade reads
structure in every language with nothing else installed; exact references,
cross-file rename and type errors on edit need the language's server —
`jade-mcp install` installs these for you, or by hand:

| Language | Install | Notes |
|---|---|---|
| Go | `go install golang.org/x/tools/gopls@latest` | First answer about 1.6s. |
| Java | `brew install jdtls` (needs JDK 21+), or your distro's package | First answer about 8.5s while it indexes. `check` runs `mvn` or `gradle`; with only the Gradle wrapper, have the agent declare `./gradlew build` once (step 4). |
| Scala | `cs install metals` ([coursier](https://get-coursier.io)) | Set `JADE_METALS_IMPORT=1` so metals may import the sbt build (it creates `.bloop/` and `.metals/`). First answer about 22s. |
| Kotlin | — | No grammar or server yet: text search only. Tell us if you need it. |

A missing server is never an error: Jade says which answers are approximate.

### 2. Point your agent at a real repository

For **Claude Code**, put this in `.mcp.json` at the root of the repository you
work in (other hosts: [Codex CLI, goose, OpenCode](#other-hosts)):

```json
{
  "mcpServers": {
    "jade": {
      "type": "stdio",
      "command": "jade-mcp",
      "args": ["--root", "/absolute/path/to/the/repo", "--tools", "core"],
      "alwaysLoad": true
    }
  }
}
```

That keeps Claude Code's own tools too. For the clearest signal, run some
sessions with Jade **in place of** them: `claude --tools ""` with the same
config ([why and trade-offs](#let-jade-replace-the-built-in-tools)). Restart
or reconnect the client (`/mcp`) after installing or upgrading Jade.

### 3. Check it came up

Ask the agent: *"call jade.capabilities"*. You should see your languages, each
with `server … (not started)` or `no server (… not installed)`, plus the build
and test commands Jade found (`mvn`, `gradle`, `sbt`, `go test`). If a server
you installed shows as not installed, that is a bug report.

### 4. What to try

Work as you normally would. If you want a checklist for the first sessions:

- **Find and follow code:** "where is X declared, and who calls it?" — `find`,
  `references`.
- **Rename across files:** a method or class used in several files — `rename`
  (exact with gopls, jdtls or metals running).
- **A change in several places at once:** "change the signature and update the
  callers, then check it builds" — `apply` with `check`.
- **Run the tests that matter:** `run_tests` with a file or test name, or `apply`
  with `check: "impact"`.
- **Repeatable commands:** have the agent `declare_command` something you run
  often (`./gradlew :core:test`, `sbt "testOnly *ParserSpec"`); later sessions
  reuse it from `.jade/commands.json`.
- **Undo:** `checkpoint` before something risky, `revert` if it goes wrong.

### 5. Tell us how it went

| When | File this |
|---|---|
| After a week or two — or when you turn Jade off | [**Feedback**](https://github.com/julianbei/jade/issues/new?template=feedback.yml) |
| The agent used the shell although a Jade tool existed | [Friction](https://github.com/julianbei/jade/issues/new?template=friction.yml) |
| A tool gave a wrong answer or failed | [Bug](https://github.com/julianbei/jade/issues/new?template=bug.yml) |
| Something you wish Jade did | [Feature wish](https://github.com/julianbei/jade/issues/new?template=feature.yml) |

The templates ask for the output of `jade.capabilities` and, optionally,
`jade.telemetry`. Neither contains source code; telemetry is
[local only](#telemetry) and records no arguments or response text, so both are
safe to paste from a private repository.

**Known rough edges on the JVM:** no formatter runs for Java or Scala files;
large Gradle builds can make jdtls's first answer much slower than 8.5s; Kotlin
has no support yet.

---

## Why Jade exists

An agent that falls back to `grep`, `sed` and `cat` is operating outside any
tooling you control. No revision tracking, no guardrails, no telemetry, no way
to know what it did or why it chose to do it that way. Every shell fallback is
a hole in your visibility.

You cannot fix that by telling the model not to use the shell. The model uses
the shell because the shell is *cheaper* — fewer tokens, fewer round trips,
more flexible. So the only durable fix is to make the structural tool the
cheaper option, and then measure whether you succeeded.

That is the entire bet, and it is testable. On this repository's own benchmark,
Jade answers seven realistic engineering questions in **0.85x** the tokens of
the equivalent shell commands. It was **5.63x** before responses became plain
text instead of JSON — see [docs/response-style.md](docs/response-style.md) for
what changed and why.

The counter-measurement matters as much. One question asked against an
unrelated repository came out at **1.36x** — worse than the shell — because an
ambiguous symbol name forced an extra disambiguation call. Seven scenarios at
home and one away disagree, both are honest, and the second is the one that
predicts outside use. The 0.0.4 pilot on four outside repositories answers
it at a larger scale: used in place of Claude Code's built-in tools, Jade
solved 12 of 12 real issues with 51% fewer tokens, and 18–25% fewer than a
shell trimmed to four tools
([docs/benchmark-results.md](docs/benchmark-results.md)). Jade is not finished.

Jade's own development log ([docs/feedback.md](docs/feedback.md)) records every
time its author reached for bash instead, and why. The pattern it found was
blunt: the fallbacks that survived longest each closed within two tasks of
being *named in the log* — not when the tool shipped.

---

## Install

### With the install script

```bash
curl -fsSL htt