jade

Jade — Just Agentic Development Environment

A change transaction for coding agents, 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).

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:

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 · how to set it up.

Status: 0.0.4 — early, usable, and looking for feedback.

go install github.com/julianbei/jade/cmd/jade-mcp@latest

Table of contents

• Why Jade exists
• Install
• Configure your MCP client
• Use it in a container
• The tools
• Repository commands
• Language support
• Design principles
• What Jade does not do yet
• Stability and versioning
• Telemetry
• Reporting problems
• Development

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 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). Jade is not finished.

Jade's own development log (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

From Go

go install github.com/julianbei/jade/cmd/jade-mcp@latest    # newest
go install github.com/julianbei/jade/cmd/jade-mcp@v0.0.4    # pinned

Lands in $GOBIN, or $(go env GOPATH)/bin if that is unset — which is usually ~/go/bin, and is not on PATH by default. Add it if it is not there, then confirm:

export PATH="$PATH:$(go env GOPATH)/bin"
jade-mcp --version

If you would rather not touch PATH, use the absolute path in your MCP client config instead of the bare jade-mcp shown below.

From a release binary

Prebuilt binaries for linux and darwin on amd64 and arm64 are attached to each GitHub release, with a checksums.txt alongside them. Each is built natively on its own platform — Jade links tree-sitter through cgo, so the linux builds need a reasonably current glibc. On an older distro, build from source or use the container image, which is statically linked against musl.

VERSION=v0.0.4
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -fsSL "https://github.com/julianbei/jade/releases/download/${VERSION}/jade-mcp_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | tar xz
sudo mv "jade-mcp_${VERSION}_${OS}_${ARCH}" /usr/local/bin/jade-mcp

From source

git clone https://github.com/julianbei/jade.git
cd jade
make binary          # bin/jade-mcp, version stamped from git describe
make install         # or straight onto your PATH

Optional: gopls

references and rename use gopls for their exact, compiler-resolved form. Without it they still work — references degrades to a textual approximation that says so in the response, and rename refuses rather than guessing.

go install golang.org/x/tools/gopls@latest

Configure your MCP client

Jade is a stdio MCP server. Point your client at the binary:

{
  "mcpServers": {
    "jade": {
      "type": "stdio",
      "command": "jade-mcp",
      "alwaysLoad": true,
      "env": {
        "JADE_WORKSPACE_ROOT": "/absolute/path/to/the/repo/jade/should/work/on"
      }
    }
  }
}

JADE_WORKSPACE_ROOT is the repository Jade inspects and edits. It does not have to be the Jade checkout — pointing it somewhere else is the entire point. A --root /path/to/repo flag takes precedence over the environment variable, and Jade prints which of the three sources it used (flag, env, working directory) at startup, so an agent can never quietly operate on the wrong repository.

Jade works on a non-git directory and on a repository with no commits yet. In both cases it says what is degraded — changes, diff, history and checkpoint need git — and everything else keeps working.

Let Jade replace the built-in tools

Jade saves tokens when it replaces the agent's own tools, not when it is added next to them. Every turn resends the whole tool list, and in Claude Code the built-in tools are about 38k tokens of it. In Jade's pilot benchmark (12 real issues in cobra, ky, requests and ripgrep, one run each):

Trimming the built-in list is most of the saving on its own. Jade on top of that used 25% fewer tokens and 24% less time than the trimmed shell, and solved the two tasks both shell setups failed. Given both Jade and every built-in tool, the agent used Bash for four calls in five and paid for both lists. To run Jade in place of the built-in tools:

claude --tools "" --mcp-config jade.json

with jade.json passing the core profile, which lists the twelve tools agents use and keeps the others callable:

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

The trade-off is real: without Bash the agent cannot run arbitrary commands. run_tests, check and repository commands declared with declare_command cover building and testing; a task that needs git operations, network access or ad-hoc scripts needs the shell back. The numbers above are one run per task — see docs/benchmark-results.md for the results, a rerun after the pilot's fixes, and the caveats.

Three things that will confuse you once

Without "alwaysLoad": true, Claude Code may never use Jade. Claude Code hides MCP tools behind a tool search by default: the agent sees their names but not their definitions, and has to search before it can call one. With its own shell and file tools right there, it does not. In Jade's benchmark, an agent given both Jade and the shell made no Jade call in three of three runs; the same setup with alwaysLoad called Jade directly. Other hosts may have their own equivalent — check that Jade's tools are actually being called.

The MCP tool catalog is fixed at connection time. A newly added tool does not appear until the client reconnects. If you upgrade Jade mid-session and a tool seems missing, reconnect before investigating.

Use the binary, not go run ./cmd/jade-mcp. A go run stanza recompiles at every process start: measured here at 284–584ms to first handshake against 14ms for the binary, with a warm build cache. A cold one is seconds. It also means the server silently changes whenever the source does — useful while hacking on Jade itself, confusing everywhere else. This repository's own .mcp.json deliberately still uses go run for that reason.

Environment variables

Use it in a container

Jade is a child process, not a service, so the useful shape is to copy the binary into your own image rather than run Jade's:

FROM ghcr.io/julianbei/jade-mcp:v0.0.3 AS jade

FROM your-project-base
COPY --from=jade /jade-mcp /usr/local/bin/jade-mcp
ENV JADE_WORKSPACE_ROOT=/workspace

Or build it yourself from the included Dockerfile.

The published image is distroless/static, so it carries no git, no gopls and no language toolchains. Jade detects each of those at runtime and degrades with an explicit message rather than failing, so this still works — you get the textual references fallback, and changes/diff/history/checkpoint are off. If you want the full surface, install git and gopls in your image; Jade will find them.

The tools

35 tools, in four groups. Every response is plain text, shaped to lead with the decisive line — the answer first, the supporting detail after, raw output only when you ask for it.

Over MCP each one is registered as jade.<name> — jade.outline, jade.replace_symbol, and so on. The tables below use the bare name for readability. Most MCP clients show you the prefixed name already, often with the dot rewritten (Claude Code displays mcp__jade__jade_find). Over the wire Jade accepts both jade.find and jade_find.

Inspect

Symbols are addressed as path::Name, or path::Name@line when a name is ambiguous. An ambiguous read returns the candidates with their signatures rather than guessing.

Modify

Every edit returns consequences, not "success": the revision transition, which symbols moved, immediate diagnostics, and the IDs of any background validation it started. Edits accept an expectedRevision precondition; supplying it makes a stale edit fail loudly instead of silently clobbering a concurrent change.

Validate

Exit status is authoritative. A command that prints a success-looking line and exits non-zero fails.

State

Project configuration

Discovery guesses how to build and test a repository from its manifests, and the guess is sometimes wrong: a Makefile's python -m pytest picks the system interpreter, npm run test runs lint and browser suites for a one-file check, and a Go module with a TypeScript app beside it has two answers to "build". A committed .jade/project.json states the answer once, the way an editor keeps its settings in .vscode/:

{
  "areas": [
    { "path": ".", "language": "go",
      "build": "go build ./...", "test": "go test ./...",
      "testName": "go test -run {name} ./..." },
    { "path": "web", "language": "typescript",
      "typecheck": "node_modules/.bin/tsc --noEmit",
      "test": "node_modules/.bin/vitest run",
      "testFile": "node_modules/.bin/vitest run {file}",
      "testName": "node_modules/.bin/vitest run {file} -t {name}" }
  ],
  "env": { "python": ".venv/bin/python", "vars": { "CI": "1" } },
  "generated": ["web/dist", "*.pb.go"],
  "notes": "Browser tests need Playwright; run unit tests by file."
}

• Areas are parts of the repository with their own language and commands, each run inside its path. check runs a kind in every area that declares it; run_tests with a file uses the deepest area containing that file, with {file} relative to the area and {name} the test name.
• Empty fields fall back to discovery, so a config can state only what discovery gets wrong. A config that does not parse, names an unknown field or a path outside the workspace fails the check instead of being ignored.
• env puts the interpreter's directory first on PATH and adds the variables to every command. generated paths are skipped by grep, find and the workspace tree. notes, with the list of areas, is sent to the agent when a session starts.
• check with dryRun says when a command comes from .jade/project.json.

jade-mcp init --root /path/to/repo drafts the file from discovery, one area, for you to review and commit; it never overwrites an existing one.

Repository commands

Beyond build and test, every repository has its own verbs — lint, codegen, migrate, release-gate — and an agent that does not know them reaches for the shell. So Jade lets it record them instead:

declare_command(name: "lint", run: "golangci-lint run ./...")
run_command(name: "lint")

They live in .jade/commands.json, which is meant to be committed. It becomes the repository's declared command vocabulary — written once by whoever (or whatever) worked out the incantation, replayed by name forever after. Calling run_command with no name lists what the repository declares; calling it with an unknown name answers with the commands that do exist, so a wrong guess teaches rather than fails.

Language support

Structure comes from tree-sitter grammars compiled into the binary, so it works with nothing installed. Semantics come from a real language server, which you provide — jade starts it on first use, reuses it for the session, and shuts it down on exit.

Every row is verified end-to-end by make conformance, which builds an image containing all eight servers and runs jade against a real repository per language.

Semantic requests wait for the server to finish indexing (its $/progress tokens), because an indexing server answers wrongly rather than slowly. When the primary server declines a rename, jade asks the language's installed alternative: ruby-lsp renames classes but not methods, so Ruby method rename needs solargraph installed alongside it. With ruby-lsp alone, method rename refuses and repeats the server's reason.

Every edit response names what checked the file (checked: pyright-langserver) or why nothing did (not checked: app.py: pyright-langserver is not installed).

Scala needs one opt-in. metals reports errors only after importing the sbt build, and it asks permission first, because importing runs sbt and creates .bloop/ and .metals/ in the repository. Jade declines unless JADE_METALS_IMPORT=1 is set, and says so in the edit response. A repository an editor has already imported needs no setting.

"Structure" is outline, symbol read, edit-by-symbol, grep and search. "Semantics" is exact references, cross-file rename, and type-level diagnostics on edit.

Jade looks for servers on PATH and in the places toolchains actually install them — ~/go/bin, ~/.cargo/bin, ~/.local/bin, ~/.coursier/bin — because go install puts gopls somewhere that is not on PATH by default, and a client that only checked PATH would report Go as unsupported on a machine that has a working gopls.

A missing server is never an error. Jade degrades to the behaviour above and says which answer you got.

Design principles

1. Structure before source. Return the minimum sufficient representation first — outline before full source, summary before raw logs.
2. Deterministic tools before model reasoning. Jade orchestrates tree-sitter, git, gopls and the project's own build tooling. It does not reimplement them, and does not guess where they could answer.
3. Every edit has a precondition and returns consequences. An edit can name the revision it expects and is refused if Jade's revision has moved; it returns the revision transition, what changed and the diagnostics — not "success". Changes made outside Jade do not yet move the revision (release plan Phase 5).
4. Conclusions before logs. The verdict leads. Raw output expands on request.
5. Semantic operations before textual ones. But textual escape hatches stay available, because the semantic path does not always exist.
6. State is explicit. Revisions, checkpoints and change sets are objects, not implications.
7. Validation waits by default, backgrounds on request. check, run_tests and run_command return the verdict; a long run can return a job to poll instead.
8. An approximation must announce itself. When Jade falls back to a text scan or a name-matched graph, the caveat travels with the data, in the response — not in documentation the agent will never read.
9. Jade is model- and harness-independent. MCP is an adapter, not the architecture.
10. Measure agent outcomes, not infrastructure sophistication. Tokens and turns per completed task — and token reduction is worthless if the success rate drops with it.
11. Repository-native execution. Builds, tests and lint run through the repository's own commands — discovered, or declared in .jade/commands.json — inside Jade, so validation is part of the record instead of a shell side trip.
12. Cheaper than the escape hatch. If the shell is easier, faster and cheaper for a workflow, Jade has failed that workflow. The benchmark, not opinion, says which (docs/benchmark.md).

The longer design document is docs/scope.md.

What Jade does not do yet

This list is more useful than the feature list — it tells you what is worth reporting and what is already known. What is planned is in ROADMAP.md.

• Nine languages get a real grammar; the rest fall back to a text scan. Go, TypeScript, TSX, JavaScript, Python, Ruby, Java, Scala and Rust are parsed properly. Anything else (Kotlin, Swift, C/C++, C#, PHP, …) is served by a heuristic that finds some declarations and misses others — and the amount it misses varies enormously by language, so treat those outlines as a hint rather than an inventory. Jade always says which you got (! no kotlin grammar — …).
• Semantic features need a language server installed for that language. Jade speaks LSP to whatever is on the machine (see Language support). With a server, references and rename are compiler-exact and cross-file. Without one, references degrades to a textual approximation that says so, and rename refuses rather than guessing — an approximate reference list is still useful to a reader, but an approximate edit is corruption.
• No completion, hover or code actions. Jade's LSP client implements what the tools need — references, rename, diagnostics — not the whole protocol.
• No blame, no cross-repo work, no remote execution.
• Formatting runs only where it is safe. gofmt and rustfmt always run. prettier (TypeScript/JavaScript), black or ruff (Python) and scalafmt run only when the repository declares them — its config file, and for Node and Python the project's own binary — because a formatter the project did not choose turns a one-line edit into a whole-file diff. Ruby, Java, JSON and Markdown are left as edited.
• Revision tracking is Jade's own counter, not git's. It detects concurrent edits within a session. It is not a VCS. A checkpoint snapshots the files Jade has edited and records git's HEAD; revert restores those files and nothing else, never moves git, and refuses once a commit has landed since the checkpoint — undoing committed work is git's job. Checkpoints do not survive a restart of the server.
• Not hardened for untrusted input. It runs shell commands you declare and edits files you point it at. Treat it as a development tool, and do not point it at a repository you would not run make in.

Stability and versioning

Tool names and required arguments are frozen and enforced by a test. 0.0.3 added no tools and made two arguments optional (query on find, path on read_range), both backward compatible. Schemas and server instructions are still read once at connection time, so reconnect after upgrading. docs/tool-contract.md has the full surface and the policy on what counts as a breaking change.

What is not frozen: response wording, the .jade/* file formats, the exact spelling of symbol IDs, and everything under internal/. Treat responses as text for a model to read, not as a format to parse. JADE_JSON=1 gives machine-readable output if you need to parse something.

Telemetry

Jade records how its own tools are used — call counts, response sizes, timing, and the failure classes that most often precede a caller giving up and using the shell.

It is written to .jade/telemetry.jsonl in your workspace and never transmitted anywhere. It records no arguments, no response bodies and no error text — only a 10-character hash of each call's target (path, symbol or query), so the confusion report can tell a second tool asked about the same thing. JADE_TELEMETRY=0 turns it off; telemetry(reset: true) clears it.

Jade tries not to leave files in a repository it was only asked to work in:

• In a git repository, before creating the log, Jade adds it to .git/info/exclude — the clone-local ignore file, never committed — unless git already ignores it. .gitignore is never touched. The log does not show up as untracked, so a harness that commits every untracked file does not commit it.
• JADE_STATE_DIR=/some/dir moves the log out of the workspace entirely, into a subdirectory per workspace. Use it when Jade is rooted at a checkout that something else commits or reviews wholesale.
• A call Jade rejects outright (an unknown tool name) never creates the log.

.jade/commands.json is different: it is the repository's declared command vocabulary, meant to be committed, and is only created when you declare a command.

It exists because response cost is invisible to whoever is reading the response. Its first live reading found a tool returning 4.6KB in 704ms on a routine call — something sixteen tasks of hand-written notes had never noticed.

Reporting problems

docs/reporting.md says what makes a useful report. There are three issue templates:

• bug — it did the wrong thing.
• friction — "I used the shell instead." This is the valuable one.
• feature — it should be able to do X.

If you are unsure which, pick friction. It is the cheapest to write and the easiest to act on, and "it was just habit" is a real answer — we want it. Every shell fallback is a place Jade was not worth reaching for, and that is the only signal that reliably improves it.

Before filing a bug, check whether your client has reconnected since the version changed. A stale tool catalog explains a surprising share of "this tool does not exist" and "my fix did not take effect".

Development

make build      # go build ./...
make test       # go test ./...
make fmt        # gofmt -w ./cmd ./internal
make binary     # bin/jade-mcp, version-stamped
make install    # onto your PATH

The repository declares its own commands in .jade/commands.json, including release-gate — build, vet, tests and a gofmt check, which is the gate a tag has to pass. Run it the way an agent would: run_command(name: "release-gate").

Layout:

Contributions are welcome. The one hard rule is principle 8: if you add a code path that approximates, the response has to say so.

License

Apache License 2.0 — see LICENSE. Copyright 2026 Julian Amelung.