Here it is:

Go ahead, evaluate something! Tick “show the messages” to see the requests and the responses going back and forth, and try (range) if you’re curious what happens to code that never finishes.

Picking an approach

An interactive nREPL playground always runs into the same problem: you need an nREPL server somewhere, and a server that evaluates code from random people on the internet is just about the worst thing you can host. (It would also cost money that I’d rather spend on something else.) So the server had to run in the browser, and I looked at a few ways to get there.

The first one was the real thing. CheerpJ is a JVM that runs in the browser, and nREPL 1.8 and Clojure 1.12 worked on it remarkably well. Every op I tried worked, stdin included! The problem was everything around that - about 8 seconds to a ready server on a fast machine, about 4.5MB to download, a busy loop that freezes the whole page unless you put the JVM in a Web Worker, and an interrupt that works only on code that’s sleeping.¹ That’s a lot to ask of someone who just opened a landing page.

The second one was scittle, which runs SCI (Michiel Borkent’s Clojure interpreter) in the browser and comes with an nREPL server, sci.nrepl. It solves a different problem, though - it lets your editor evaluate code in a page, through a relay that runs in babashka or on the JVM, and its replies differ from nREPL’s in quite a few places. (I’ve filed some issues about those.) nbb has a pretty complete nREPL server of its own, but it runs only on Node.

None of those fit, so I ended up writing a small nREPL server for SCI that runs entirely in a web page, with the page as its client - nrepl-sci. SCI does all the heavy lifting, and evaluation, completion and docs lookup took just a few hundred lines of ClojureScript. The whole thing is about 230KB gzipped and it’s ready in a fraction of a second. Not bad, right?

The hard part

A basic nREPL server is easy enough. The trouble starts with two ops most people never think about - interrupt and stdin.

JavaScript gives you one thread, and SCI evaluates code in one go. While (loop [] (recur)) runs nothing else does, so the server can’t even read the interrupt request that would stop it, and code calling read-line can’t wait for input without blocking the very thread that would receive it. There’s a third problem hiding in there as well. nREPL sessions are supposed to be independent, so an eval in one session (say, your editor’s) shouldn’t hold up another one (say, a test runner connected to the same server).

Here’s how nrepl-sci deals with all of that:

• The server runs in two Web Workers. A supervisor takes the requests, queues them, and answers interrupt and stdin itself, while an evaluator runs SCI.
• The two share some memory (a SharedArrayBuffer) that serves as a mailbox. The evaluator waits for mail with Atomics.wait, which blocks a worker without spinning, so read-line waits for its input there, much like it would on the JVM.
• SCI calls a hook of your choice on every function call and every recur. nrepl-sci uses it to check its mailbox, to see if it’s been interrupted, or if there’s a request from another session it could take in between. Checking on every call made code noticeably slower, so it checks on every 256th call, which still means every few microseconds. Benchmarks run about as fast as without any of this.
• Endless seqs like (range) and (iterate inc 0) check as they go, so (count (range)) stops when you interrupt it.
• Some code never calls back into SCI - a regex that backtracks forever, for instance. The supervisor gives it a second to stop, then kills the evaluator and starts a new one. Your sessions survive that, but everything you evaluated in them is gone.

In the end the supervisor, the evaluator and the mailbox took more code than the nREPL server itself, which tells you something about where the complexity is.

Note: All of this works only when the page is cross-origin isolated, as browsers hand out SharedArrayBuffer only to pages served with the Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers.

Sadly, GitHub Pages, which hosts both nrepl.org and this blog, can’t send those. Without them nrepl-sci falls back to doing one thing at a time: read-line throws, and interrupting code means starting over, which is exactly what you saw if you tried (range) above. Evaluation, output, errors, completion and doc work the same either way, though.

Testing with proof

Back in 2023 I listed the lack of a protocol compatibility test suite among the things people hate about nREPL, and asked if one of you was looking for a fun small OSS project. Eventually I took my own advice and started proof, and nrepl-sci is the first server I’ve written with proof around from day one. It made a huge difference! Building an nREPL server used to involve a lot of guessing, as the protocol is small, but what clients actually expect from a server is spread across their source code.

A proof profile is a short TOML file that tells proof how to start your server and how to say a few things in its language: a value, some output, an exception, reading a line, code that runs until it’s stopped. proof run takes it from there, with checks covering the protocol and the exact requests CIDER, Calva, Conjure, vim-fireplace, REPLy and neorepl send. When a check fails, proof also tells you why it matters:

FAIL   robust.sessions-at-once      An eval in one session doesn't hold up the others
       clone request got no reply with "done" within 10s
       why: Each client has sessions of its own (e.g. an editor and neorepl,
       connected to the same server), so a server that runs one eval at a time
       leaves every other client waiting for whatever the code in one of them
       does.

That’s a check you can easily shrug off when you’re writing a server for a playground, and it’s the reason nrepl-sci takes requests in between at all. Working on the server mostly came down to running make proof after every change. Today nrepl-sci passes all 73 checks that apply to it (the other 5 are about things like vim-fireplace, which needs Java). Without shared memory it fails exactly two: stdin.need-input and robust.sessions-at-once. I guess that’s a pretty good summary of what you give up without cross-origin isolation.

If you’re working on an nREPL server of your own, I can’t recommend proof enough. It also comes with a GitHub Action, so your CI can run it as well.

The tradeoffs

Nothing comes for free, and nrepl-sci is no exception:

• It’s SCI, not Clojure. You’re getting ClojureScript as interpreted by SCI, so there are no Java classes, no JVM libraries, and some corners of the language behave differently. That’s fine for a playground, but not for anything that needs your real project.
• There’s no JavaScript interop. SCI blocks it unless you allow it, and nrepl-sci doesn’t, so (js/alert "hi") and even (.toUpperCase "hi") fail. Admittedly, that’s a bit annoying, but it’s also what makes nrepl-sci safe to embed anywhere, as the code people type can’t touch the page, or even the worker it runs in. (clojure.string/upper-case works just fine.)
• A request from another session runs on top of the code it interrupted, so that code can’t stop until the request is done, and a read-line taken in between holds it until it gets its input. You’d need two clients fighting over the same server to notice.
• Starting over loses your definitions, which matters most without cross-origin isolation, where every interrupt starts over.
• It’s about 1MB of JavaScript (230KB gzipped), loaded the first time you use the REPL. That’s nothing compared to CheerpJ, but it’s not free either.

Using nrepl-sci yourself

nrepl-sci was built for nrepl.org, but nothing in it is specific to the site.

You can embed a REPL in a page - documentation, a tutorial, a blog post. The worker takes the bencode of each request as a Uint8Array and posts back the bencode of each reply, so the whole integration boils down to something like this:

const worker = new Worker("/assets/js/nrepl-sci-worker-0.1.0.js");
worker.onmessage = (event) => console.log(decode(event.data));
worker.postMessage(new TextEncoder().encode(encode({ op: "eval", code: "(+ 1 2)", id: "1" })));

encode and decode are a few dozen lines of bencode, and the REPL in this post is about 170 lines in total, styles included - have a look. Grab nrepl-sci-worker.js from the latest release and serve it from your own site, as browsers start workers only from the page’s own origin. If you can send the cross-origin isolation headers, you get stdin and proper interrupts for free. nrepl.org’s playground is a bigger example, with completion, history and the wire windows.

You can also test nREPL clients without a JVM. The Node build is a regular nREPL server on a socket (node nrepl-sci.js --port 7888) that’s up in about a tenth of a second, which makes it handy for the test suites of clients and editor plugins.

Finally, if you’re after an nREPL server for some other language that runs on a single thread, the supervisor and the mailbox might give you a few ideas. The server itself knows nothing about threads or sockets, and the trick with the mailbox works for any interpreter that can call back now and then while it runs.

What’s next

The obvious next step is getting cross-origin isolation on nrepl.org. A service worker can add the headers GitHub Pages won’t send, at the cost of a reload when it’s first installed, so I might try that on a page of its own. I’d also like to allow some harmless interop, so that (.toUpperCase "hi") works as people expect, and to publish nrepl-sci on npm.

Epilogue

Back in 2018 I wrote that there was “the big dream to port nREPL to ClojureScript”, so it could be used in self-hosted environments, and in 2023 I was still hoping we’d see more native ClojureScript nREPL servers. nrepl-sci isn’t quite that dream - it’s a much smaller nREPL server for SCI - but it’s a step in that direction.

Big thanks to Michiel Borkent for SCI, which did most of the hard work here. None of this would exist without it! And, as usual, special thanks to Clojurists Together for supporting my work on nREPL!

That’s all I have for you today. Play with the REPL, try to break it, and let me know how it went! Keep hacking!

Running tests

,test in the REPL, or neorepl test in your shell, runs the tests in the namespaces you name, the tests you name or, without either, the whole project’s. Failures come with their file and line, and errors with a stack trace that stops at the test that hit them, instead of wandering off into clojure.test’s guts. ,retest (neorepl retest) reruns only what didn’t pass, which is exactly what you want while you’re fixing things.

As usual, the server does the heavy lifting. cider-nrepl runs the tests when it’s around, and so does babashka’s nREPL server, which bundles CIDER’s test ops these days. Without either, neorepl falls back to plain clojure.test, as long as you tell it which namespaces to test. And in a ClojureScript session the same commands run your ClojureScript tests.

$ neorepl test
$ neorepl test my.app-test my.app.db-test
$ neorepl test --format json my.app-test/start-test

Stack traces and the inspector

,stacktrace shows the last error full-screen. Pick a frame, press Enter, and its source opens in your $EDITOR at that line (as a copy, for code in a jar), and when you quit the editor you’re back where you were. By default you see only the frames that matter, and a brings back the rest - the REPL’s own machinery and the repeated frames of the same function. With cider-nrepl, i inspects the cause you’re looking at and d its ex-data. After a test run with errors, ,stacktrace shows those, each under the test it came from. (You can see that at the end of the GIF above.)

,inspect puts cider-nrepl’s inspector (babashka has one too) in full-screen:

The arrow keys (or j and k) move around, Enter digs into a value and Backspace goes back up, [ and ] page through big collections, v shows an object’s fields, P toggles pretty printing and g refreshes values that change, like an atom’s. The handiest one is d, which defines whatever you’re looking at as a var. Dig five levels deep into some big API response, press d, give it a name, and you can play with that piece in the REPL right away.

neorepl inspect does the same one step at a time, for scripts and agents, since the inspector keeps its state in the session:

$ neorepl inspect '(System/getProperties)'
$ neorepl inspect --push 3
$ neorepl inspect --def props

Tracing

,trace traces a function, or every function in a namespace, and from then on each call shows its arguments and what it returned, nested in the calls it’s part of. It’s often the quickest way to see what some code is actually doing, and there are no printlns to forget to remove afterwards. Calls on other threads, like an HTTP handler’s or a future’s, show up above the prompt too. ,trace without arguments lists what’s traced and ,untrace stops tracing. Scripts and agents get neorepl trace, with the calls showing up in the output of the neorepl eval that made them. Tracing needs cider-nrepl on the server.

(Fun fact: tracing a function that the tracing itself calls, like clojure.core/map, used to take the whole server down. neorepl refuses to trace those, and as of orchard 0.48 the server no longer falls over on them anyway.)

Coding agents

0.3 was all about coding agents. The CLI was usable by agents from day one, but now they get a lot more help:

• neorepl mcp serves neorepl’s features as MCP tools over stdio, for agents that would rather call tools than run commands. With Claude Code it’s a one-liner:

  $ claude mcp add neorepl -- neorepl mcp
  

  The tools are eval, load, doc, source, where, apropos, macroexpand, reload, test, retest, pst, interrupt, check and ports. That’s fewer than the CLI’s commands on purpose: an agent pays for every tool’s description in its context on every turn, whether it uses the tool or not. Evaluations get cut at 10,000 characters and interrupted after 60 seconds by default, so a stray (range) or an infinite loop can’t eat the agent’s context or its session.

• A skill teaches agents the workflow I’d like them to follow: after editing a file, check its parens, load it, run its tests, and read the stack trace when something fails. It costs nothing until the agent actually works on Clojure code. doc/agents.md explains how to set it up with Claude Code, Codex, Gemini CLI, Cursor and VS Code.

• neorepl check --fix repairs unbalanced delimiters the way parinfer’s indent mode would, trusting the indentation over the parens. Mismatched parens are still the most common way for an agent to break a Clojure file, and now fixing them doesn’t take another trip through the model:

  $ neorepl check src/demo/orders.clj
  src/demo/orders.clj:3:1: Unclosed (
  $ neorepl check --fix src/demo/orders.clj
  src/demo/orders.clj:3:1: Unclosed (, repaired from the indentation
  

The CLI and the MCP tools share named sessions, the one called agent unless told otherwise, which brings me to my favourite addition in 0.4.

Looking over your agent’s shoulder

,sessions lists the server’s named sessions, and ,sessions agent steps into the agent’s, with its name in the prompt. Everything the agent left behind is right there: its namespace, its *1, its *e. So when an agent tells you that a test fails with a NullPointerException, you can look at the exception yourself instead of asking it to paste the stack trace. ,sessions - takes you back to your own session.

The lookups take --session too, so neorepl doc --session agent foo looks up foo the way that session sees it, in its namespace and its language, ClojureScript included.

The REPL, round two

0.4 also spent a lot of time on the REPL itself:

• ,ns switches namespaces, loading the one you name if it isn’t loaded yet, and lists the project’s namespaces when you don’t name one.
• C-x C-s shows the source of the symbol at the cursor and C-x C-a the vars whose names contain it, next to the C-x C-d for docs that was there from the start. All three come from rebel-readline.
• ,doc and the arglists that show up as you type cover Java classes, methods and fields too, with their Javadoc as text (that one needs cider-nrepl).
• ,edit and the stacktrace browser open definitions that live in jars, instead of telling you they can’t.
• Ctrl-C got a lot more reliable. An interrupt sent right after an evaluation could get lost when the server hadn’t started running it yet, the forms after an interrupted one ran anyway, and whatever an interrupted evaluation printed later could show up in the next one’s output. All fixed.
• neorepl sends the forms you enter to the server one at a time now, which is a big part of the interrupt fixes, and as a bonus piggieback evaluates all of them, not only the first.
• On Linux, every evaluation used to wait 40ms on the server’s socket, courtesy of TCP’s delayed ACKs. neorepl turns those off now, on the JVM and on babashka 1.13.227 or newer, and evaluating a file with 100 forms went from 4.5 seconds to about 150ms.
• Lots of error messages got friendlier: a build tool that isn’t installed, a server that dies while starting, loading a file with unbalanced parens, a named session the server lost when it restarted, and so on.

So much for keeping neorepl small, by the way - the code has about doubled since 0.1. In my defense, it does a lot more than twice as much.

Making the neighbours better, round two

Just like last time, building neorepl turned up problems elsewhere, and a good part of these two weeks went into fixing them at the source:

• I filed a batch of issues for babashka’s nREPL server: test runs that hung or killed the session, :project? being ignored, a session that never answered again after its client disconnected, a couple of JLine classes neorepl’s line editor needed. Michiel fixed every single one of them within days, and they’re all in babashka 1.13.227. Thanks, Michiel!
• cider-nrepl 0.64 and orchard 0.48 came out this week with fixes for the problems I ran into: what tests print now comes back with the test results (it used to go to the connection of the session’s previous message, which for a CLI is long gone), the test op no longer goes silent for a namespace that isn’t loaded or runs every test when the one you asked for doesn’t exist, ClojureScript tests run on shadow-cljs, a traced call that throws shows up as such, and Javadoc no longer comes with stray spaces in it. CIDER gets all of that too, which is my favourite kind of side effect. neorepl 0.4.1, out the day after this post, uses cider-nrepl 0.64 when it starts a server.
• In nREPL, the fix for an interrupted evaluation’s last response going to the wrong connection is merged, and so is TCP_NODELAY on the server’s sockets, which takes 100 evaluations with nREPL’s own client from 4.4 seconds to 90ms on Linux. Both will be in the next nREPL release.
• The piggieback improvements I mentioned last time are a bit behind schedule. A lot of ClojureScript REPLs run on top of piggieback, so a mistake there has a pretty big blast radius, and evaluating every form of a message is something we never found a good way to do in the past. I’d rather take my time with those than rush them out. neorepl isn’t waiting on them, at least, since it sends the forms one at a time now.

What’s next

0.5 is about more runtimes and better navigation:

• integration tests against real servers in CI: cider-nrepl and babashka first, then shadow-cljs and piggieback with Node
• nbb and Basilisp in CI, with their gaps documented
• cross-references (,refs), on top of cider-nrepl’s fn-refs and fn-deps
• a full-screen namespace browser
• a couple of ideas borrowed from clojure-cli.repl: evaluating the form at the cursor, and the last evaluation’s outcome and time in the prompt
• indenting continuation lines, and a way to pick the vi keymap

Better Windows support, the one item from the 0.1 list that’s still open, is planned for 0.6, together with easier ways to install neorepl.

Try it

$ bbin install io.github.nrepl/neorepl
$ cd my-project
$ neorepl

The CHANGELOG has everything I skipped here, and the README has the details. Please keep the issues and ideas coming!

Keep hacking!

Why another REPL?

There’s no shortage of Clojure REPLs, so it’s fair to ask. Here’s what I was after:

• nREPL all the way down. neorepl only speaks nREPL, so it works with anything that runs an nREPL server: Clojure, babashka, shadow-cljs, Basilisp, ClojureCLR and so on. The smarts live on the server. When cider-nrepl is there neorepl uses it, the same way CIDER does, and when it isn’t it falls back to nREPL’s built-in ops, and then to evaluating a bit of code.
• A REPL that’s pleasant to use: a proper line editor, highlighting, completion, arglists as you type, pretty printing, history per project and a Ctrl-C that actually interrupts the evaluation.
• A CLI that’s just as good for scripts and coding agents. Every lookup the REPL can do is also a command, with structured output and exit codes that mean something.
• Something small and modern. Clojure 1.10+, nREPL and JLine 4 are the only dependencies, and the same code runs on the JVM and on babashka. The whole thing is about 3,300 lines right now, and I’d like to keep it that way.

rebel-readline and bb repl --connect are both great, and I borrowed from them freely, but neither tries to be an nREPL-first tool with CIDER’s tooling, jack-in and a CLI for agents. That combination is the whole point of neorepl.

Update (2026-10-11): A few people asked how neorepl relates to the Clojure CLI REPL, which the Clojure team released a couple of weeks ago, and to bb repl --connect. (I’m a bit embarrassed to admit I hadn’t heard of the former until after I announced neorepl.) Funny enough, all three are nREPL clients under the hood, but they’re after pretty different things. In practical terms:

• The Clojure CLI REPL runs only on the JVM and needs Clojure 1.12+. It ships its own nREPL server, and its docs and data inspector are ops of that server, so against any other server you can only evaluate code. It’s deps.edn only. Its editing is really nice, though - structural editing, evaluating the form at the cursor and a datafy-based inspector - and I’ll be borrowing some ideas from it. It doesn’t do completion yet.
• bb repl --connect puts babashka’s console REPL in front of any nREPL server, with completion, arglists and docs, in very little code. It’s a great way to poke at a running server, but it won’t start one for you.
• neorepl works with any nREPL server and gets the most out of the ones with cider-nrepl (or babashka’s take on it), without any middleware of its own. It starts a server for Leiningen, deps.edn, babashka and shadow-cljs projects, follows you into ClojureScript, and everything the REPL does is also a command with JSON output for scripts and agents. No structural editing yet, however.

So, if you want the fanciest line editing and you live in deps.edn land, give the Clojure CLI REPL a try. If you want CIDER in your terminal, for you and for your agents, that’s what neorepl is for. The neat part is that babashka’s server bundles CIDER’s inspector and test runner ops these days, so neorepl’s test runner (already on main) and the inspector that’s coming next work with babashka out of the box.

For humans

Here’s the REPL in action:

A few things worth pointing out:

• Enter only submits the input once its forms are complete, so pasting a whole function just works.
• TAB completes, with the candidates’ types next to them, and the arglist of the function you’re calling shows up after the cursor.
• Values get pretty printed on the server and highlighted on the client.
• Commands start with a comma, the CIDER way: ,doc, ,source, ,apropos, ,macroexpand, ,pst, ,reload, ,edit (which opens a definition in your $EDITOR) and ,help for the rest. The Clojure reader sees a comma as whitespace, so they can’t clash with real code.
• Ctrl-C interrupts what’s running, and code that reads *in* gets its input, something REPLy never quite got right.

Without a server to connect to, neorepl starts one for the project, the way CIDER’s jack-in does, with cider-nrepl on the classpath, and stops it when you exit. It knows Leiningen, the Clojure CLI, babashka and shadow-cljs projects.

ClojureScript works too. Start a ClojureScript REPL in the session (through shadow-cljs or piggieback, which jack-in adds for you) and neorepl follows along: evaluation, completion, docs and the rest switch to ClojureScript, and :cljs/quit takes you back.

For agents

Coding agents are surprisingly good at Clojure, as long as they have a REPL to talk to. Most of them drive CLIs much better than anything else, so neorepl has a CLI that’s meant to be driven:

• neorepl eval evaluates code on the project’s server. Calls share a session, so *ns*, *1 and *e carry over from one call to the next, and --session keeps separate lines of work apart.
• --format json (or edn) gives you the values, the output and the namespace as data.
• --timeout interrupts the evaluation before giving up, so an infinite loop doesn’t take the server down with it, and --max-output keeps a stray (range) from eating the agent’s context.
• neorepl check finds unbalanced parens, brackets and braces without a server. That’s the most common way for an agent (or a human) to break a Clojure file.
• neorepl doc, source, apropos, complete, where, macroexpand and reload do what the REPL’s commands do.
• neorepl server starts a server that stays up, for editors, agents and neorepl eval to share.

The exit codes are boring on purpose: 0 when all went well, 1 for an evaluation error, 3 when there’s no server to talk to and 124 for a timeout (like timeout(1)).

Playing nicely with nREPL

A new client is also a new way to break servers, or to be broken by them, and the nREPL world has quite a few servers these days. Fortunately I’ve been working on proof, a compatibility suite for nREPL, which made neorepl a good test subject.

proof checks both sides of the conversation. proof proxy sits between a client and a server and grades everything the client sends: every request has an id, need-input gets answered with stdin in the right session, and so on. proof serve is a small nREPL server that can behave like other servers in very specific ways - sending only the last value of the code like Basilisp and jank, dropping stderr, having no interrupt op, splitting output into one message per character, and so on. I ran neorepl’s REPL and CLI through both, against nREPL, babashka, Basilisp and jank, and through every quirk proof serve knows about.

neorepl came out of it in decent shape, but not unscathed:

• Code read from stdin (neorepl eval -) that then read *in* itself crashed neorepl and left the evaluation waiting on the server for input that was never coming.
• neorepl’s errors could leave the shell’s prompt dangling at the end of a line with servers that don’t end their error reports with a newline (hello, jank!).
• neorepl eval exited with 1 when it lost the server, which is the status for code that failed.

All of those are fixed in 0.1. It also turned up a couple of things that are nREPL’s fault rather than neorepl’s: need-input and the end of an interrupted evaluation can go to the wrong connection when a session is used from more than one. Those will be fixed in nREPL itself.

It works the other way around too. proof now checks servers with the exact requests neorepl sends while starting its REPL and evaluating code, next to the ones CIDER, Calva, Conjure, vim-fireplace and REPLy send, so a server that breaks neorepl finds out from proof, not from a bug report. nREPL, babashka, Basilisp and jank all pass those checks today.

Making the neighbours better

Building neorepl turned up a few problems elsewhere, which is one of my favourite side effects of writing a new client. piggieback used to evaluate only the first form you sent it and silently drop the rest, and it loaded the ClojureScript compiler at startup even when nobody asked for a ClojureScript REPL, which added almost half a second to the startup of every server with ClojureScript on the classpath. The fixes for both (piggieback#162 and piggieback#161) will be in the next piggieback release. The Node.js REPL in ClojureScript itself doesn’t cope well with interrupted evaluations, and that one is next on my list.

What’s next

0.1 is the foundation. Here’s what I’d like to tackle next:

• a test runner with proper reports
• a full-screen inspector and stacktrace browser
• an MCP server and a ready-made skill for coding agents
• better Windows support

Try it

The easiest way to install neorepl is bbin:

$ bbin install io.github.nrepl/neorepl
$ cd my-project
$ neorepl

The README has the details.

It’s early days, so I’m sure you’ll find rough edges. Please file issues, and tell me what you’d like to see next. And if you’re one of the people who kept lein repl and REPLy going over the years - thank you! neorepl wouldn’t exist without you.

Keep hacking!

These days plenty of RuboCop runs aren’t started by a person at all. Claude Code, Codex, Cursor and friends run it after every batch of edits, read whatever it prints and try to fix what it found. That’s a very different user from the one RuboCop was built for. An agent has endless patience, but everything RuboCop prints ends up in its context window, and it can’t glance at a terminal and tell what’s obviously noise. So I spent most of this cycle making RuboCop a better citizen in that world.

Output an agent can act on

--format json now tells you exactly what autocorrection would do with each offense. Every correctable offense carries the edits, and whether a plain rubocop -a would apply them:

"correction": {
  "safe": true,
  "edits": [
    {
      "start_line": 1,
      "start_column": 6,
      "last_line": 1,
      "last_column": 12,
      "begin_pos": 5,
      "end_pos": 12,
      "replacement": "'hello'"
    }
  ]
}

A cop that crashes on a file is now listed with that file’s results, instead of only on stderr, where nothing that parses JSON ever looks. (And the --parallel notice no longer goes to stdout, where it used to break the JSON output. Oops.)

There are also a few new options aimed squarely at agents (humans are welcome to use them too):

• --max-offenses-per-cop=N caps how many offenses each cop reports. A legacy codebase can easily have thousands of Style/StringLiterals offenses, and an agent doesn’t need to read all of them to get the idea.
• --explain COP prints what a cop checks, its good and bad examples, its configuration as your project resolves it, and whether it autocorrects. Offense messages are terse by design, and often that’s not enough to fix the code the way the cop actually wants.
• --show-cops and --show-docs-url now complain about cop names they don’t recognize instead of silently ignoring them. Agents make up plausible-sounding cop names more often than you’d think.

A much better MCP server

Koichi added an experimental MCP server back in RuboCop 1.85, and in this release it got a serious overhaul:

• rubocop_inspection answers in the same shape as --format json instead of as LSP diagnostics. LSP diagnostics are great for editors, but an agent had to wade through 0-based lines and quick fixes it had no use for, and the results were about twice as big.
• A new rubocop_explain tool does what --explain does.
• Inspection and autocorrection take only, except and changed, so an agent can check just the files it touched, or just Lint.
• Autocorrection can preview its changes as a diff, reports the offenses it couldn’t fix, and leaves alone the files it has nothing to correct in.
• Cops with AutoCorrect: contextual, like Lint/UselessAssignment, are held back by default, since the code is probably mid-edit. An agent that’s done editing can ask for them with contextual: true.
• A cop crashing on one file no longer fails the entire request.

The server is still marked experimental, but it’s in a much better place now. If you’re using it with your agent of choice, I’d love to hear how it goes.

Agents and rubocop:disable

There’s a new AI Agents page in the docs that covers all of the above, plus a few lines you can drop into your AGENTS.md or CLAUDE.md so the agent knows how your project wants RuboCop run.

It also deals with my favorite agent “fix” - the # rubocop:disable that makes the offense go away. Banning directives outright is too blunt, since some offenses really are better left alone, but you can make the agent explain itself:

Style/DisableCopsWithinSourceCodeDirective:
  Enabled: true
  AllowWithReason: true

Now every directive needs a -- justification, and whoever reviews the change gets to decide whether the reason holds up.

Sandboxes

More and more agents run in sandboxes that only allow access to the project directory. Filesystem calls outside of it fail with EPERM, and RuboCop was mostly prepared for EACCES, so a cache it couldn’t write to took the whole run down with it. Now it just carries on without the cache. One more crash of that kind, in the lookup of your target Ruby version, has a fix lined up for the next release.

Autocorrection you can trust

This one isn’t specific to agents, but agents are the ones who suffer the most from it. A person notices when -a produces garbage. An agent might happily build on top of it. This release has a mountain of bug fixes, and most of them are about autocorrection - dozens of infinite loops between cops, and an even longer list of corrections that produced broken (or subtly different) code. Plenty of them came out of a systematic audit of our autocorrections, and Koichi, viralpraxis and Starlexxx fixed a staggering number of them.

The rest of the release

• Lint/UselessAssignment now catches a variable that a block keeps assigning but nothing ever reads.
• Security/JSONLoad now reports JSON.load(src, create_additions: false). Before json 2.17 the option is ignored in that position, so the “safe” call wasn’t safe at all. JSON.load(src, nil, create_additions: false) works everywhere.
• Style/NegativeArrayIndex is now marked as unsafe.
• --changed, --diff and the SARIF formatter, all new in 1.91, got a round of fixes.
• RuboCop no longer loads net/http on every run, only when it fetches a remote config.
• regexp_parser 2.11.3 or newer is now required.

The release notes have the full list.

Epilogue

Agents are already a big part of how RuboCop gets used, and I think we’re only getting started on adapting to that. Next on my list is --changed-lines, so an agent (or a person) can focus on the offenses in the lines it actually changed. If you’re running RuboCop through an agent and something about it annoys you, tell us.

One more thing before I go - rubocop.org got completely reworked recently. Most of what it shows now comes straight out of RuboCop itself, there’s an index of every cop, and there’s a playground that runs RuboCop right in your browser, courtesy of ruby.wasm. Go check it out and take the playground for a spin! Feedback on the new design and features is most welcome - just open an issue if something looks off or you’re missing something.

Big thanks to everyone who contributed to this release! Koichi, viralpraxis and Starlexxx carried the bug-fixing once again, and bquorning reported the sandbox crash that got me looking into the rest of them.

That’s all I have for you today. Keep hacking!

Since the beginning of time…

…certain people have been unhappy with RuboCop’s defaults. I wrote almost exactly that sentence six years ago, right before RuboCop 1.0, when I ran a survey to work out which of our defaults were wrong. Some good came out of it - that’s how Layout/LineLength ended up at 120 - but a survey has an obvious weakness. It asks people what they prefer, and people are terrible at reporting what they actually do.

So this time I went looking for evidence instead of opinions. I built a small tool that grabs the 500 most-starred Ruby repos on GitHub, resolves whatever .rubocop.yml they ship (following inherit_from chains and popular inherit_gem bases like standard and rubocop-rails-omakase), and tallies what they change about our defaults. 233 of them have a config, and the results were interesting in various ways:

• Style/Documentation is turned off outright by 53% of them. It’s the most disabled cop by a wide margin.
• Seven of the ten most disabled cops are Metrics cops.
• Our Metrics/MethodLength default is 10; the median project that touches it sets
  1. AbcSize goes from 17 to 28. ClassLength goes from 100 to 300.
• 91% of the projects that set Style/StringLiterals pick double_quotes - and all three of the big shared configs people inherit wholesale already default to it.

Note: people write a line of config only when they disagree with us, so happy users are invisible here. This shows how far opinionated projects drift from us, not how everyone feels. Evidence, not proof. Still - when a third of the most visible Ruby projects out there disable a cop, that cop isn’t teaching anyone anything. It’s just noise people have learned to mute.

Knowing is the easy part

Knowing which defaults are “wrong” and being able to change them are two very different things. We follow SemVer (semi-)religiously, and changing a default - a cop’s Enabled state, a Max threshold, an EnforcedStyle - is a breaking change that has to wait for a major release. That’s exactly the promise we made in RuboCop 1.0, and I have no intention of walking it back.

Same story for a cop that starts reporting a case it used to miss, or corrects one differently. Those aren’t new cops, so pending is no help - they change results for everyone who already has the cop enabled.

Which leaves us with a lovely little trap. Everything interesting piles up in a queue waiting for a major release; the major release gets scarier the longer the queue grows; so it gets postponed; so the queue grows some more. You can see where this ends. In the 1.0 post I wrote that RuboCop 2.0 would “probably arrive in less than 8 years”, and we’re six years in. I’d very much like to beat my own estimate. I really do!

Enter preview (mode)

Preview mode is our way out of that trap. It’s an opt-in channel where the next major release’s behavior lives until that release ships:

AllCops:
  Preview: true

Or, for a single run:

$ rubocop --preview

It gates three kinds of things. A cop’s entry in the default configuration can now carry a Preview section holding the defaults it’s expected to adopt in 2.0:

Style/Documentation:
  Enabled: true
  Preview:
    Enabled: false

A cop can also hide an unstable behavior change behind a preview? check and ship it in a minor release. And a cop that’s too speculative to even be pending can ship as Enabled: preview. In all three cases your own configuration still wins over the default one, exactly as it always has.

The line between preview and pending is worth keeping straight, as both mean “not on by default”. When a new cop gets introduced it’s usually pending (and sometimes disabled) - a marker for a pending decision (from you or us). If we’re asking you to help us find out if something is a good idea, it’s preview.

I know that’s a bit confusing right now and perhaps down the road preview will replace pending completely for simplicity’s sake. That’s to be determined at this point. Some ideas and thoughts on this front are most welcome!

One thing to be clear about: preview behavior is unstable and can change or be withdrawn in any release. That’s the whole point. It makes trying something out cheap for us, and telling us we got it wrong cheap for you.

I’d love to tell you the idea was original, but it wasn’t. It came out of an afternoon spent looking at how other linters handle this problem, and they had all landed in much the same place. Ruff has had a preview mode for a while now - one global switch gating both preview-only rules and changed behavior inside existing ones - and we copied that model wholesale. Clippy parks its unfinished and contested lints in a nursery group that stays off until they’ve earned their keep. Both admit the same thing: if the only way to try something is to ship it to everyone at once, you’ll never try anything.

What’s in the box today

1.91 ships the mechanism and a first batch of proposed 2.0 defaults, taken straight from that corpus data. Flip preview on today and you get:

• The entire Metrics department off. Not because measuring complexity is a bad idea, but because our thresholds are so far off that people disable the cops rather than argue with them. I’d rather ship no opinion than a bad one.
• Roughly two dozen contested Style, Naming and Layout cops off - Style/IfUnlessModifier, Style/GuardClause, Style/ClassAndModuleChildren, Style/DoubleNegation, Style/FrozenStringLiteralComment, Style/BlockDelimiters and friends. They’re all near the top of the disable leaderboard.
• Style/Documentation off, obviously.
• The community’s EnforcedStyle wherever it differs from ours: double_quotes for Style/StringLiterals, brackets for Style/SymbolArray and Style/WordArray, and consistent/indented/with_fixed_indentation across the multiline indentation family.
• AllCops: FailLevel: warning, so style offenses get reported without failing your build. More on this one in a moment.
• Exclude merging with the default configuration and with inherited files instead of replacing them - the fix for #9325, one of our oldest configuration papercuts.

That’s 34 cops switched off and 17 defaults adjusted. A start, not a destination.

A less prescriptive RuboCop

I want RuboCop 2.0 to ship a much smaller and much less prescriptive default configuration than 1.x does.

This isn’t a new idea for me. Back in the 10th anniversary post I admitted that “we might have gone overboard at times in our desire to improve Ruby codebases”, and I listed bundling cops into presets as one of the things I wanted for 2.0, to address “the common complaint that RuboCop checks for way too many things out of the box”. Four years later that complaint hasn’t gone anywhere, and now I’ve got the numbers to back it up.

There’s a slightly embarrassing part to this story too. It wasn’t until I was digging through that data that it hit me how many cops we ship these days. 613. I’ve been maintaining this project for fourteen years and that number genuinely shocked me. Sure, I knew it was a lot - I’d just never looked at the figure, and once you have, it’s hard to unsee. That’s what got me focused on making the default configuration leaner.

RuboCop grew up as the “enforcement” arm of the Ruby Style Guide, and for many years “is it in the style guide?” was a good enough answer to “should it be on by default?”. I still stand firmly behind the style guide. But the tool has outgrown that framing - that’s an awful lot of opinions to hand someone on their first day, and the data says most people don’t want most of them. Out of the box RuboCop should catch real problems and stay out of your way on matters of taste. If you want the full sermon, you should have to ask for it.

Sure, this sounds a lot like Standard, and I have no problem admitting they got there before we did. The popularity of Standard and rubocop-rails-omakase was the community telling us something, and we took our sweet time listening. The difference is that RuboCop will stay exactly as configurable as it’s always been. I’m not taking away any knobs, I’m changing which ones start in the “on” position.¹ If your project loves our current defaults, you’ll be able to keep every last one of them.

Preview isn’t the only thing in motion here, either. The presets work I promised in that anniversary post is moving again - #14005 has the discussion and #14994 a first prototype - and I see the two as related rather than competing. Preview asks “is this particular default wrong?”. Presets ask the broader “how many cops should be running at all?”, by letting you pick a bundle - something essential, something recommended, the full style guide - instead of arguing over several hundred separate decisions. And the preview feedback feeds straight into that: every cop you tell me you don’t miss is a cop that belongs in a stricter tier, and every one you yell at me about belongs in the baseline. I’d like to land both for 2.0.

The severity work in this release is part of the same push. A cop’s default severity now comes from its department, so Security cops report as warning and Metrics cops as refactor. Combined with the new AllCops: FailLevel - the configuration equivalent of --fail-level, which somehow we never had - you finally get a better dial than “everything fails the build equally”:

AllCops:
  FailLevel: warning

With that, only Lint and Security offenses (plus anything you’ve bumped yourself) fail the run. Everything else still gets printed, it just doesn’t paint your CI red.

The rest of the release

Preview stole the show, but there’s plenty else in here - and a few of these came out of that same survey of the competition:

• --diff prints a unified diff of what autocorrection would change, without touching a single file. This is the CI check I’ve wanted for ages - the build fails with the patch that would fix it sitting right there in the log, and rubocop --diff --format quiet | git apply gets you that patch locally.
• --changed inspects only the files git says changed, defaulting to a diff against HEAD (any revision works, and untracked files count). It pairs beautifully with --diff.
• There’s a SARIF formatter now, so rubocop --format sarif --out rubocop.sarif feeds straight into GitHub code scanning and your offenses show up annotated on the pull request diff.
• Lint/MisplacedMagicComment is a new cop that flags magic comments Ruby silently ignores - an # encoding: comment that isn’t on the first line, a # frozen_string_literal: true that drifted below a require, a magic comment that pushed a shebang off line one. Quietly doing nothing is the worst failure mode a magic comment can have.
• Two new directives. # rubocop:enable-next re-enables a cop for exactly one statement, with no closing directive to maintain. # rubocop:next covers the same statement scope but takes push-style +/- arguments, for the rare case that needs toggles in both directions at once. Style/DirectiveScope will convert your existing pairs to the tighter forms.
• Lint/CopDirectiveSyntax is enabled by default now, so a directive that silently suppresses nothing gets reported instead of fooling you for years. It absorbed Style/DoubleCopDisableDirective, which is gone.
• Style/DisableCopsWithinSourceCodeDirective gained an AllowedDirectives option, so you can ban hand-written disable comments while still letting generated rubocop:todo entries through. Its cop lists match department names too now.
• And a mountain of bug fixes - a long parade of infinite loops between cops squashed, more crashes and bad autocorrections than I care to admit to, and two result cache bugs, one of which could serve one file’s cached results for another file. The release notes have the full list.

Epilogue

The most useful thing you can do right now is run rubocop --preview on your codebase and tell us what you think. Which of those disabled cops do you actually miss? Which EnforcedStyle did we get wrong? What did we leave switched on that should have gone? That’s the whole reason preview exists - I’d much rather find out now than on the day 2.0 ships. Open an issue, comment on the defaults discussion, or just yell about it on the internet. I’ll find it.

Big thanks to everyone who contributed to this release! viralpraxis and Starlexxx in particular did a huge amount of the bug-fixing this cycle, and Koichi keeps being Koichi. And thanks to everyone who’s been arguing with our defaults all these years - turns out you were mostly right.

That’s all I have for you today. Keep hacking!

Last time I said that I had plucked most of the low-hanging fruit and that the next two months were unlikely to be as productive. Well, I was wrong. CIDER 2.0 finally shipped, and once it was out the door I used the momentum to sweep through pretty much every corner of the nREPL/CIDER ecosystem. A few long-neglected projects got proper releases, and nREPL got a couple of brand new implementations in languages I play on the side from time to time.

The big highlights from my perspective:

• CIDER 2.0 (“Terceira”) is out, followed by 2.0.1, and 2.1 is taking shape on master
• clj-refactor 4.0 is out
• Sayid went from 0.4 to 0.8 in the span of three weeks
• Drawbridge, nREPL’s HTTP transport, got its first meaningful release in years
• nREPL went polyglot: nREPL servers for Erlang and Elixir and an OCaml client
• clj-suitable 0.7 and 0.8 closed most of the gap between ClojureScript and Clojure completion
• A lot of work landed on nREPL’s master (TLS hardening, URL-based connections, docs) and a new release is right around the corner

Below you’ll find more details about the work I did, project by project.

CIDER

CIDER 2.0 (“Terceira”) landed on July 15, right on the schedule I had announced in the preview post. For once in my life I was actually on time! The big themes were covered there and in the release announcement (transient menus, inline macro stepping, call-graph browsers, source-based find-references, the tracing and tap buffers, rich content in the REPL), so here’s just what changed between the preview and the final release:

• cider-doctor, which checks your Emacs setup and the active nREPL session for common problems and produces a report you can paste in a bug report
• an orchard value for cider-print-fn, selecting cider-nrepl’s much faster orchard.pp pretty-printer
• SSH tunnels now forward a free local port, so remote REPLs sharing a port no longer collide on localhost
• C-c C-d at the stdin prompt sends end-of-input, and stdin is routed to the exact connection that asked for it
• a long tail of nREPL client fixes: a slow memory leak on the eldoc/completion path, nrepl-dict-merge mutating a shared literal, notifications treated as format strings

CIDER 2.0.1 followed a week later with fixes for the problems early adopters ran into: evaluation in a dependency’s source buffer erroring with “No linked CIDER sessions” (in several variants), cider-enlighten-mode never lighting anything up (a 1.22 regression), the macroexpansion commands refusing to expand let/fn/loop, and load-file potentially freezing Emacs on a huge result. Nothing dramatic, but I’m glad people were quick to report those.

After that master (the future CIDER 2.1) kept moving at a steady pace. A few of the things that landed there:

• CIDER’s dynamic font-locking (REPL-defined macros, functions, deprecated/instrumented/traced symbols) now works better in clojure-ts-mode buffers via tree-sitter. Previously it worked “officially” only under clojure-mode. The debugging reader tags are highlighted there too.
• A new cider-preferred-clojure-mode controls which mode CIDER uses to font-lock the code it renders - REPL results, doc examples, overlays and its own display buffers. clojure-ts-mode is finally a first-class citizen in CIDER.
• Symbol prompts can go through completing-read (so Vertico/Ivy/Helm kick in) and completion annotations render as an aligned type/namespace column in Corfu, Vertico and the built-in *Completions*. More on this in Modernizing CIDER’s Completion.
• Connecting got smarter. Container-published nREPL ports are resolved for /docker: and /podman: buffers, lein trampoline REPLs are detected, .nrepl-port files are no longer discarded on systems without lsof, and there’s a new “How CIDER Finds Ports” section in the manual.
• Every form command got an “at point” variant (inspect, pprint, macroexpand, format, insert in REPL), there’s a cider-inspect-menu listing every way to start an inspection, and the contents of comment forms are treated as top level by the whole defun command family.
• Stray output from long-lived background processes (say, a core.async go-loop still printing under a finished eval’s id) is now routed to the REPL instead of being dropped with a warning.

One more thing. I shipped “smarter form targeting” on master - the evaluation commands resolving the form from where the cursor actually is, rather than the form before it - wrote about it, got a lot of feedback, and reverted it a few days later. CIDER 2.1 will keep the classic Emacs semantics. Fifteen years in, the existing behaviour is the contract, not an implementation detail I get to tidy up. The detour wasn’t wasted, though: it surfaced a bug where the text of a line comment was treated as code, and the “at point” family of commands is a direct result of it.

cider-nrepl

Three cider-nrepl releases in July, wrapping up the tools.deps migration and driving the CIDER 2.0 launch:

• cider-nrepl 0.62.0 finalized the Leiningen to tools.deps migration, simplified deferred middleware loading, documented the op response keys (with a test verifying the descriptor contract) and shipped the hardened content-type and slurp middleware that made rich content safe to enable by default.
• cider-nrepl 0.62.1 fixed a whole cluster of debugger bugs. Record literals no longer get downgraded to plain maps by instrumentation, deftype/defrecord method bodies are skipped (goodbye Unable to resolve symbol: STATE__), and enlightening deftest bodies works again.
• cider-nrepl 0.62.2 pruned trace and tap subscriptions with dead transports (a dead subscriber used to break every traced evaluation), stopped the debugger from shadowing enlighten’s evaluator, brought the docs back in sync with the code and added a section for tool authors.

Orchard

Orchard 0.44.0 shipped on July 4, mostly thanks to Sashko’s inspector work (a replace command, truncated table columns, ARef contents rendered fully). My part was a round of tests for the less covered namespaces and, later on master, a fix for orchard.print ignoring custom print-method implementations for records and collections. Thanks, Sashko!

clj-refactor 4.0

clj-refactor.el 4.0 is the release I had been promising for a few cycles. It requires Emacs 28.1+ and CIDER 2.0+, and it’s a big one:

• project-wide refactorings (rename symbol, change signature, inline symbol) now show a diff preview before touching disk, and cljr-undo-last-refactoring reverts the last one in a single step
• the slow refactorings run asynchronously, so Emacs no longer freezes while the middleware analyzes the project
• cljr-change-function-signature can add and remove parameters and handles multi-arity functions
• a clj-refactor-menu transient replaces the hydra menus, and the multiple-cursors, hydra and inflections dependencies are gone
• many commands degrade gracefully without a REPL (cljr-clean-ns, cljr-slash, cljr-add-missing-libspec, cljr-remove-let, cljr-promote-function)
• cljr-slash can add and hotload a missing library, artifact lists are cached, and the namespaced refactor-nrepl ops are used when available

I still think the long-term home for the most useful bits is CIDER and clojure-mode, but at least the project is in good shape while I figure that out. There’s a bit more in the release post.

clj-suitable

clj-suitable, the ClojureScript completion backend, was another project that had been coasting for years:

• clj-suitable 0.7.0 adapted to Piggieback 0.7’s delegating repl-env, modernized every dependency, replaced the Leiningen build with tools.build, moved CI to GitHub Actions and added a shadow-cljs integration test over a real Node runtime.
• clj-suitable 0.8.0 brought the static completion much closer to compliment: fuzzy matching (pr-fn completes print-function), compliment-style ranking, completion of local bindings (destructuring included) and of referred vars inside :refer vectors. It also fixed the REPL’s *1/*2/*3 getting clobbered by completions and a few long-standing shadow-cljs and Node.js issues.

ClojureScript users - I’d love to hear how the new completion feels in practice.

Sayid

The Sayid revival continued at a brisk pace, with five releases between July 1 and July 17:

• Sayid 0.4.0 dropped the com.billpiel namespace prefix, added data-returning variants of the workspace and query ops, and introduced a client-rendered, foldable tree view of the recorded call tree built on CIDER’s cider-tree-view.
• Sayid 0.5.0 made recording bounded: a record limit, per-function limits, sampling, a max trace depth and bounded printing. Tracing a namespace under a test suite can’t eat all your memory anymore.
• Sayid 0.6.0 rebuilt inner tracing on tools.analyzer.jvm, replacing the fragile source-rewriting instrumenter.
• Sayid 0.7.0 added sayid.data (the recorded call tree as plain data, with tap> integration for Portal and friends) and sayid.golden, a golden-trace testing helper.
• Sayid 0.8.0 focused on the experience: a sayid-menu transient, plain-language feedback from the trace commands, getting-started hints in empty views, and a fix for the inspector integration that had been broken for years.

I wrote a bit more about the last one here. Not bad for a project that was completely dead in June, right?

Drawbridge

Drawbridge is nREPL’s HTTP transport, created by Chas Emerick in 2012 and “technically maintained” ever since. I finally gave it the attention it needed:

• Drawbridge 0.3.1 updated the dependencies (nREPL 1.7, Ring 1.15) and throttled client polling so it stops flooding servers with GET requests.
• Drawbridge 0.4.0 is the interesting one. It adds drawbridge.bridge, a local nREPL socket server that relays to a remote Drawbridge endpoint, so any socket-based client (CIDER, Calva, rebel-readline) can now talk to Drawbridge. There’s also a WebSocket transport with server push instead of long-polling, bearer-token authentication via secure-ring-handler (which refuses to run unauthenticated unless you insist), and a deps.edn, so it’s usable as a git dependency.

The full story is in Lowering the Drawbridge.

nREPL

No nREPL release this cycle, but master is shaping up nicely for 1.8:

• the built-in command-line client can connect using a URL, including the nrepls:// and nrepl+unix: URLs that TLS and filesystem-socket servers advertise, and http(s):// when Drawbridge is on the classpath
• TLS hardening: descriptive errors for invalid key material, Ed25519 keys, tolerating a swapped certificate order, and a documented security model
• the built-in client sends input to the server as raw text, so reader typos, auto-resolved keywords and custom tagged literals no longer crash it
• stdin fixes: EOF arriving behind buffered input is reported properly, and a race between the stdin consumer and producer is gone
• nrepl.spec finally matches what describe and ls-sessions actually send
• a pile of documentation debt cleared (lookup return values, the session-closed status, the -f/--repl-fn option, middleware best practices) and a CI check keeping ops.adoc in sync with the descriptors
• Clojure 1.10 is the new minimum and nrepl.misc/requiring-resolve is gone in favour of the core one

The nrepl.org site also picked up links to several new clients and servers (Nautilos, nREPL.hx for Helix, Janet and Steel Scheme servers). The nREPL family keeps growing, which makes me happy every single time.

nREPL on the BEAM

nrepl-beam is a brand new project I started in July, mostly because I wanted to see how well the nREPL spec holds up when implemented from scratch outside the JVM. It’s home to:

• dialtone, an nREPL server for Erlang (and a server core for the whole BEAM)
• repartee, the Elixir server built on top of it
• chaser, a terminal nREPL client that works with any nREPL server

nrepl-beam 0.1.0 shipped on July 14. Both servers implement the full op set (eval with streamed output, sessions, interrupts, stdin, load-file, completions, lookup) and pass neat’s cross-implementation integration suite alongside Clojure, Babashka and Basilisp. Writing them was a good test of the spec, and it produced a few of the documentation fixes listed above. Turns out that the best way to find holes in a spec is to implement it in a language you barely know.

mezcaml

In the same spirit, mezcaml is a minimal nREPL client for OCaml: a small client library plus a command-line REPL, working against any nREPL server regardless of the language on the other end. No release yet, but the core protocol works, it reads whole forms, and it has server-driven completion. Nothing serious - it was a fun way to combine my recent OCaml hacking with nREPL.

clojure-mode, clojure-ts-mode and MrAnderson

Smaller things: the #_ toggle commands in clojure-mode were renamed to clojure-toggle-discard and friends (matching Clojure’s own terminology, old names kept as aliases), both modes got a :to-have-face matcher for font-lock tests, and clojure-ts-mode now checks the indentation of its sources on CI.

MrAnderson 0.7.1 added a command-line interface, so it can be run without Leiningen, and reworked its downstream integration tests against cider-nrepl and refactor-nrepl, which had silently stopped exercising local changes. Oops.

Blog posts

I wrote a lot this summer, mostly a series on the notable changes in CIDER 2.0:

• Lowering the Drawbridge
• CIDER 2.0: Sky is the Limit
• clj-refactor.el 4.0
• Simplifying Session Management in CIDER
• Stepping Through Macros in CIDER
• Sayid 0.8
• clj-suitable 0.8.0: Closing the Gap with Compliment
• Making CIDER More Discoverable
• Modernizing CIDER’s Completion
• Closing the Find-Usages Gap in CIDER
• Sharpening CIDER’s Debugging Tools
• Leveling Up CIDER’s ClojureScript Support
• Smarter Form Targeting Is Coming to CIDER
• Smarter Form Targeting Is Not Coming to CIDER

Epilogue

Big thanks to Clojurists Together, Nubank and the other organizations and people supporting my Clojure OSS work! None of this would have happened without you. You rock!

As for what’s next - CIDER 2.1 is the obvious milestone, and it’s mostly a matter of letting the clojure-ts-mode integration settle. After that I’d like to cut nREPL 1.8 with the TLS and URL work, and get mezcaml and the BEAM servers to a point where they are useful to someone other than me. I won’t make any predictions about productivity this time around. Clearly I’m bad at those.

Keep hacking!

This is not a sad story, though. The detour turned up a bug that was quietly mangling people’s comments, and CIDER came out of it better than it went in.

What I was actually after

The targeting change wasn’t really about cursor positions. What I wanted was for every CIDER command that operates on a form to behave the same way, without adding yet another command to get there. CIDER has an enormous surface of evaluation commands, and every “at point” variant I could have added would have made that worse. If the existing commands simply resolved the form you meant, newcomers would have had fewer commands to learn, not more.

That was the bet: consistency by redefinition rather than by addition. In hindsight it was the wrong bet for a project this old. Fifteen years in, the existing behaviour isn’t an implementation detail I get to tidy up - it’s the contract. And as it turned out, the redefinition wasn’t nearly as transparent as I’d convinced myself it was.

The feedback

Several users, including CIDER’s co-maintainer Sashko Yakushev, voiced concerns and flagged issues I’d overlooked while playing with this initially. The most important one: inspection is just another flavour of evaluation, and people inspect bare symbols constantly. If it got the same treatment, the disruption would be real enough to run a fork over.

My instinct was that this was an edge case, so I measured it instead of arguing. Across every cursor position in a buffer, only three rules actually differ, and the flagship flow - type a form, hit C-x C-e - is identical under both. Two of those three were fine. The third was this one:

The cursor doesn’t move between those two evaluations. That’s the same position, twice, and the answers differ - "b" under the classic rules, "ab" under the new ones.

I’d filed “cursor on a closing paren” as an oddity nobody hits deliberately. But think about when you land there: you finish typing the last thing inside a form, and the cursor is now sitting on the ). For someone inspecting symbols all day, that fires constantly. And the classic answer isn’t arbitrary either - as Sashko put it, the rule of thumb is “whatever paredit-backward jumps back to”, which is a better description of the tradition than anything I’d written down.

Why the tradition exists in the first place

Here’s the part I under-weighted, and it’s worth spelling out for anyone who finds “the form before the cursor” arbitrary.

Emacs form navigation overwhelmingly leaves the cursor after a form. C-M-f (forward-sexp) moves over the next form and stops just past its closing delimiter. C-M-e (end-of-defun) leaves you after the whole top-level form. C-M-n (forward-list) does the same for the enclosing list. Paredit’s paredit-forward behaves the same way, and so does typing: finish a form and the cursor is, by definition, right after it.

So “evaluate the preceding form” isn’t a quirk - it composes with how you already move around. Navigate forward over a form, evaluate it. Type a form, evaluate it. The cursor is already in the right place, every time.

Getting onto a form instead takes deliberate effort: C-M-b (backward-sexp), C-M-a (beginning-of-defun), paredit-backward, or a jump package like avy. All perfectly good tools, but you have to reach for them - unless you’re clicking around with a mouse, in which case the cursor lands wherever you pointed and “the form before the cursor” genuinely is useless. Which, I suspect, is exactly the workflow difference behind this whole argument.

What CIDER got instead

The half of the idea that was never controversial is still there, as commands you opt into rather than a new meaning for keys you already use. Every operation now has an “at point” variant, not just eval and tap: cider-inspect-sexp-at-point, cider-pprint-eval-sexp-at-point, cider-macroexpand-1-at-point, cider-macroexpand-all-at-point, cider-format-edn-sexp-at-point, cider-insert-sexp-at-point-in-repl.

Three ways to say which form you mean, and now every command supports all of them:

The at-point commands fall back to the preceding form when there’s nothing to point at, so they’re drop-in replacements rather than a separate mode of working. Which means anyone who wanted smart targeting can simply have it:

(with-eval-after-load 'cider-mode
  (define-key cider-mode-map (kbd "C-x C-e") #'cider-eval-sexp-at-point)
  (define-key cider-mode-map (kbd "C-c C-e") #'cider-eval-sexp-at-point))

Two lines, no hidden mode, and everyone else’s fingers keep working. This is what I should have shipped in the first place, and it’s what the manual now recommends. Yes, it’s more commands than I wanted. It’s also the version that doesn’t break anyone.

Macroexpansion is the one place a bit of cleverness survived on its own merits, because an expansion needs a call form. Stand on a bare symbol and cider-macroexpand-1-at-point widens to the call around it, since expanding a lone symbol is never what anyone meant.

The bug at the bottom of the hole

While unifying the plumbing I found this, which is much worse than anything form targeting was ever guilty of. Put the cursor at the end of a comment:

(defn foo [])
;; a comment|

CIDER answered comment. Not the (comment ...) form - the word, lifted out of your prose, because sexp motion has no notion of comments once the cursor is inside one and happily reads the words as symbols.

For evaluation that produced a puzzling error. For the in-place macroexpansion commands, which replace the region they resolved, it did this:

;; a comment          ->   ;; a EXPANDED<comment>
(+ 1 2) ; hey         ->   (+ 1 2)          ; EXPANDED<hey>

It rewrote the comment. That bug has been in CIDER for years, and I only found it because I went looking at the primitives while cleaning up after myself.

Then I checked the neighbours, and this is my favourite part of the whole episode: SLIME, SLY and Emacs Lisp itself all still do this. Both Lisp environments use a bare backward-sexp, and if you put the cursor after (+ 1 2) ; hey in any Emacs Lisp buffer and ask for the preceding sexp, you get hey. CIDER now steps out of the comment first, which as far as I can tell makes it the only one of the family that gets this right.¹

One idea worth stealing

The same survey turned up something CIDER was missing. SLY briefly flashes the region it compiled, so you see what it acted on. That’s a direct answer to the confusion this whole saga was about - “which form did it just take?” - and it changes nothing about what gets taken.

(setq cider-flash-evaluated-region t)

Off by default, because I’ve learned my lesson about switching things on for everyone. But if the targeting rules ever puzzle you, turn it on for a day.

The moral

In the original post I described cider-form-targeting, the escape hatch back to the classic rules, as “living on borrowed time” - clutter left over from a plan I’d since reversed, which I was itching to delete.

That option is the only reason the conversation stayed a conversation. Its existence made the objection “please don’t remove the fallback” rather than “I’m forking CIDER”, and I very nearly removed it before anyone had tried the change.

Every mistake is a learning experience for me, and this one was cheap: nothing had shipped, so the whole thing cost a few days and some rewriting. The testing and feedback cycle worked exactly as it should have - people tried something on master, told me plainly what was wrong with it, and the result is better than either what I proposed or what we had before. Everyone gets the behaviour they want, and CIDER lost a text-eating bug on the way.

Thanks to everyone who took the time to tell me I was wrong.

That’s all I have for you today. Keep hacking!

NOTE: Update: this didn’t survive contact with its users, and CIDER 2.1 ships with the classic behaviour after all. See /posts/2026/08/29/smarter-form-targeting-is-not-coming-to-cider.html for what the feedback was, what replaced it, and the rather nasty bug the detour turned up.

A bit of history

Emacs has a very particular tradition when it comes to evaluating code: eval-last-sexp (the venerable C-x C-e) acts on the expression before the cursor. Not the one you’re looking at, not the one you’re inside of - the one that ends exactly where your cursor stands. SLIME follows this tradition, Emacs Lisp itself follows it, and for the past 15+ years CIDER has followed it too.¹ If you grew up in Emacs, this rule is in your fingers and you’ve never once thought about it.

Here’s the thing, though - most people using CIDER didn’t grow up in Emacs. And many of them never programmed in Emacs Lisp and Common Lisp with SLIME. They came to Emacs because of CIDER (or Clojure in general), and for them the rule is invisible, arbitrary and mildly hostile. You put your cursor on a form, you press the eval key, and CIDER cheerfully evaluates… something else. Meanwhile every other modern Clojure environment - Calva, Conjure, the various vim plugins - resolves the form from the cursor position and just does what you meant.²

For a long time I resisted changing this, mostly out of respect for the Emacs tradition (and my own muscle memory). But at some point I had to admit that I was optimizing for the wrong audience. CIDER’s users are mostly casual Clojure hackers who happen to use Emacs, not Emacs experts who happen to write Clojure. The tradition was serving me, and confusing them.

What’s actually changing

The evaluation commands (and their macroexpansion, inspection and tapping siblings) now resolve “the form the cursor indicates”. Concretely, with | marking the cursor:

(map inc |(range 10))

Pressing C-c C-e here used to evaluate inc - the form before the cursor, which is almost never what you wanted. Now it evaluates (range 10) - the form your cursor is pointing at.

(str "hello" " " "world"|)

This one used to evaluate "world" (really!), because the last complete expression before a cursor sitting on the closing paren is the final string. Now it evaluates the whole (str ...) call.

Macroexpansion benefits too:

(when tru|e (launch-missiles))

C-c C-m here used to complain that true is not a macro. Now it expands the enclosing (when ...) call, because expanding a bare symbol is never what anyone means.

And my favorite one - the rich comment workflow is now consistent everywhere:

(comment
  (calculate-all-the-things|))

Every defun-level command - eval, pretty-print, inspect, debug - now treats the form inside the (comment ...) as the top-level one. Evaluating a whole comment form returns nil by definition, which has exactly zero uses, so CIDER no longer does that no matter which command you reach for.

Why you probably won’t notice

Here’s the part I’m most pleased with: the new behavior agrees with the old one at every position where “the form before the cursor” made sense. Cursor right after a form? Same result as always. Cursor in the whitespace after a form? Same. Cursor in the middle of a symbol? Same. The two behaviors only diverge where the classic answer was something nobody ever wanted - a previous sibling, a lone trailing atom.

So if your muscle memory follows the Emacs tradition, nothing changes for you. If it doesn’t - CIDER stops punishing you for it. That’s the whole change.

Reverting to the classic behavior (for now)

If you do want the traditional rules - maybe you genuinely use “evaluate the previous sibling while standing on an opening paren” - one setting restores them exactly:

(setq cider-form-targeting 'preceding)

There’s also a per-session toggle in the eval menu (C-c C-v T) that shows the active mode in the mode line while you experiment.

This option is probably living on borrowed time, though. I added it back when I planned to keep the classic behavior as the default and offer smart targeting as an opt-in. Now that the roles are reversed, an option whose only job is restoring rules almost nobody deliberately relied on doesn’t really make much sense, and lately I’ve been trying to trim that kind of clutter from CIDER, not add to it. Don’t be surprised if the option quietly disappears - possibly even before the release ships. Which is one more reason to speak up now if the classic behavior genuinely matters to you.

Farewell, “last sexp”

This change forced my hand on something I’d been putting off for years - the command names. cider-eval-last-sexp is a fine name for a command that evaluates the last sexp. It’s a lie for a command that evaluates the form your cursor indicates. So the commands got honest names:

• cider-eval-last-sexp is now cider-eval-form
• cider-eval-defun-at-point is now cider-eval-defun (the -at-point never carried information)
• likewise for the pprint/tap/inspect/insert variants

Every old name keeps working as an alias, so your config and your M-x habits are safe. But why “form” and not “sexp”? Beyond the targeting change, there’s a Clojure-specific reason: in Clojure a form isn’t always a single sexp. ^:private x is two sexps but one form; so is #inst "2024-01-01". The commands operate on forms - the reader’s unit of evaluation - and now they say so.³ The manual’s evaluation docs got a proper glossary explaining all of this.

Closing thoughts

All of this is on master and in the MELPA snapshots today, ahead of the next stable release. I’d really love for people to play with it before the release ships - especially if you’re an Emacs veteran whose fingers disagree with my reasoning, or a newcomer for whom this was supposed to just work. Did we get the resolution rules right? Does anything still surprise you?

Share your feedback on the CIDER discussions board, in #cider on the Clojurians Slack, or just file an issue. This is exactly the kind of change that’s easy to adjust before a release and painful after - and the fate of the compatibility option depends on what I hear.

That’s all I have for you today. Keep hacking!

Most of it came out of an annoyance I’d been living with for years without ever quite naming it: a lot of what I work on isn’t one directory. CIDER is really CIDER plus cider-nrepl plus orchard plus clj-refactor plus a handful of others. RuboCop is RuboCop plus rubocop-ast plus rubocop-rails and the other extension gems plus the style guide. I’ve been maintaining families of repositories for the better part of a decade.

Lately I’ve also been reaching for git worktrees far more than I used to, so the same repository is now checked out two or three times on my disk at any given moment.

Projectile saw all of that as a pile of unrelated projects, which is exactly what it looks like from the outside.

Somewhere else in the same project

projectile-switch-worktree (s-p W) offers the other checkouts of the repository you’re in, each labelled with whatever tells it apart - the branch for git, the workspace name for Jujutsu:

Switch to worktree:
~/src/myapp-main/     (main)
~/src/myapp-hotfix/   (hotfix/crash-on-open)

Git worktrees are the obvious case. Projectile asks git about those, so a worktree you’ve never opened in Emacs shows up anyway. Jujutsu workspaces work the same way.

The case I care about more is the one without any plumbing: a second git clone of the same upstream. Same workflow, done by hand. I looked at my own ~/projects while writing this and found four separate clones of CIDER sitting in it. Nothing records those anywhere, so Projectile can’t ask git to list them - it matches them among your known projects by their remote instead.

Somewhere else in the same effort

The other half is projectile-switch-sibling-project (s-p n), which offers the projects related to the one you’re in rather than every project on the machine.

The interesting question was what “related” should mean. My first instinct was to compare directory names and look for a shared prefix. Before writing anything I tried the candidates out on my actual project directory, all ninety-odd repositories of it.

Comparing names does find rubocop, rubocop-ast and rubocop-rails. But grouping by the owner of the upstream remote finds this:

Half of those names have nothing in common with cider, and no amount of staring at directory names would ever have related them. haystack parses stack traces, port is a printer registry, sayid is a tracing debugger. Nothing in those names says “CIDER”.

What they do have in common is an org: they all live under clojure-emacs on GitHub. That’s not incidental, it’s how the project is actually organised - the org is the boundary of the effort, and the individual repositories are just where the pieces ended up when they got big enough to split out. Same story for the rubocop org, and for nrepl. Once I saw that, keying on the owner of the remote was obviously right, because it’s the same fact GitHub is already recording for me.

It needs a bound, though, and the same experiment showed why: about 40% of my checkouts are under my own GitHub account, and “we’re both under bbatsov” doesn’t relate anything. So an inferred group covering more than a quarter of your known projects gets dropped and the next signal takes over.¹ If you’d rather just say what belongs together, projectile-project-groups is there and is never second-guessed.

Switching is only the obvious thing to do with this. Now that Projectile can tell which projects belong together, the same grouping could back a find-file or a search across the whole family - one prompt that reaches every repository in the org rather than just the one you happen to be sitting in. I go looking for “which of these fifteen repos defines this var” often enough that I suspect it’s the more useful half. Nothing built yet, but that’s where I expect this to go.

The commands come with you

Once Projectile knows two directories are the same repository, the command history can follow you between them.

Press M-p at the compile or test prompt in a worktree you made this morning and you get the commands the project is actually built with, instead of an empty history. That’s an issue from 2022 that a stale bot had helpfully closed for me at some point.

What doesn’t follow you is anything that runs without asking - what a prompt is pre-filled with, and what projectile-repeat-last-command replays. I had those shared too in the first draft, and then watched a repeat in one worktree rebuild the tree next door. A remembered command can carry absolute paths back to where it was typed.

More languages, fewer surprises

projectile-run-test-at-point (s-p c .) arrived in 3.1 knowing Python, Go and JS/TS. It now also knows Ruby (both RSpec and Minitest), Rust, Elixir, Java, Erlang and F#.

Ruby is written the same way whichever framework you use, so there the project type picks the runner rather than the syntax; Java’s picks between Maven and Gradle. Elixir tests get addressed as FILE:LINE, because ExUnit can’t select a test by name from the command line. OCaml deliberately gets nothing - its tests are ordinary values you register with Alcotest or OUnit, so there’s no syntax to recognize.

projectile-find-file-of-kind (s-p j) and projectile-toggle-related-file (s-p J) learned Phoenix, Laravel and Next.js. Rails and Django had been the only frameworks with file-kinds tables out of the box, which felt like a strange place to have stopped.

The reports answer back

The dashboard and the doctor from 3.3 both got a pass. They’re no longer plain text - section headers, field labels and findings are faced by meaning, with findings colored by severity and sorted so anything wanting your attention comes first. The faces only inherit from standard ones, so your theme styles them without knowing Projectile exists.

The doctor’s findings now come with a button that acts on them:

[enable] for a projectile-mode you forgot to turn on, [enable caching] on a big uncached project, [open dirconfig], [edit .dir-locals.el]. Pressing one regenerates the report. Findings Projectile can’t act on stay plain advice.

And since a doctor report usually ends up pasted into an issue, w copies the buffer as plain text, without the faces and buttons.

Odds and ends

• projectile-find-changed-file (s-p C) completes over what git reports as staged, unstaged or untracked - or, with a prefix argument, everything that differs from a revision you pick.
• projectile-run-task discovers rake tasks now, read out of your Rakefile and .rake files rather than by running rake -T, which would load the whole application.
• projectile-ignored-project-patterns is the regexp-matching sibling of projectile-ignored-projects, so keeping a whole area of your machine out of the known projects no longer needs a lambda.
• Messages Projectile emits on its own initiative are prefixed with [Projectile] now, and the ones answering a command you just invoked aren’t. There were five different conventions in there before, which I’d somehow never noticed.
• The known projects file, the frecency store and the session directory are resolved with locate-user-emacs-file, so they land in the right place if your configuration lives in ~/.config/emacs. Nothing moves if it doesn’t.
• Elixir’s implementation/test toggle offers foo_test.exs rather than foo_test.ex, a script ExUnit will actually run. Project types can declare their test file extension now.

Upgrade notes

Nothing here should break a working setup, but two things are worth knowing.

A batch of options were renamed or folded together. The six projectile-<cmd>-use-comint-mode options became one projectile-use-comint-mode; projectile-per-project-compilation-buffer and projectile-per-command-compilation-buffer became projectile-compilation-buffer-scope; and a handful of options that had broken their own naming schemes were renamed to match their siblings.² Every one of them is still honored under its old name, so your config keeps working - you’ll just see an obsolescence notice.

Two options are gone: projectile-tags-file-name and projectile-go-project-test-function were only ever read as Projectile loaded, which means setting them from your init file afterwards did precisely nothing.

And the command history is now the repository’s rather than the directory’s. Set projectile-command-history-scope to project if you’d rather have it per directory. Histories you already have are adopted, not dropped.

The full changelog is here, and the manual is at docs.projectile.mx. The cross-repository features have a page of their own, limitations included.

Five releases in six weeks is not a pace I intend to keep up, and this is the natural place for the burst to land. The big pieces from 3.0 through 3.3 have had their corners sanded down, and what’s left on my list is smaller and less interesting to write about. Which is roughly where a fifteen-year-old package ought to be.

That’s all I have for you today. Keep hacking!

The single-file curse (limitation)

For its entire existence RuboCop has analyzed your code one file at a time. That’s not an accident - it’s a deliberate design choice that has served the project extremely well. A file-at-a-time analyzer is simple, it’s fast, and it parallelizes trivially across all your cores. It’s a big part of why RuboCop can lint a huge codebase in a few seconds.

The catch is that a cop looking at a single file is essentially working with blinders on. It has no idea what’s defined in the rest of your project. And that turns out to be a real limitation for a whole class of checks:

• Is this method a duplicate of one defined in another file? No way to tell.
• Does this constant actually refer to what I think it does, given the surrounding namespaces? Can’t resolve it without the whole picture.
• Does this class really need a super call in its constructor, or does none of its ancestors define initialize? RuboCop can’t see the ancestry, so it has to play it safe.

Faced with questions like these, cops have only ever had two options: bail out and say nothing (a false negative), or guess and risk yelling at perfectly good code (a false positive). Neither is great. Over the years we’ve papered over this with configuration knobs - things like AllowedParentClasses for Lint/MissingSuper, where you manually list the base classes RuboCop can’t see for itself. It works, but it’s the kind of busywork a tool should be doing for you.

Enter rubydex

rubydex is a library from Shopify that does exactly what RuboCop historically couldn’t: it builds a project-wide index of your code - a graph of every declaration and reference, with the ancestry and resolution worked out. Give a cop access to that index and suddenly it can answer all those cross-file questions with confidence.

We introduced optional support for rubydex back in 1.87, and 1.89 is where it really starts to pay off.

I want to stress the word optional here. rubydex is a separate gem with native (Rust) extensions, and using it means paying for an indexing pass and some extra memory. That’s a perfectly reasonable trade for the extra smarts, but it’s not a trade everyone wants to make, and it shouldn’t be forced on anyone. RuboCop’s default experience should stay lean and dependency-light - no native code, no index, no surprises. So rubydex is opt-in, and I fully expect it’ll stay that way for the foreseeable future. If you want the cross-file superpowers, you flip a switch; if you don’t, nothing changes for you.

Turning it on is two steps. Add the gem to your Gemfile:

gem 'rubydex', require: false

And enable the flag in your .rubocop.yml:

AllCops:
  UseProjectIndex: true

Everything below happens automatically once the index is available - there’s no per-cop opt-in. And if the gem isn’t installed, RuboCop just prints a friendly warning and falls back to its usual file-local behavior.

What the index unlocks in 1.89

This release wires the index into a good chunk of the cop library. Here’s a tour of what you get.

There are a few brand-new cops that simply couldn’t exist without a project-wide view:

• Lint/NameTypo is my personal favorite - it catches typos in constant and method names by checking them against everything defined in your project and suggesting the closest match. So Services::UserCraetor.new gets flagged with a helpful “did you mean UserCreator?”, and the same goes for a fat-fingered method call like Report.generate_sumary. It’s careful to only speak up when it’s confident (the name has to be unresolvable and have a close sibling), so it stays quiet on genuinely external names.
• Lint/DeprecatedReference flags calls and constant references to any API you’ve marked with a YARD @deprecated tag, anywhere in the project. Tag a method as deprecated in one file, and every stray use of it elsewhere lights up. It’s a lovely way to drive a gradual migration off some old code.
• Lint/UnusedPrivateMethod does project-wide dead-code detection - it reports private methods that are never referenced anywhere in the indexed project. It’s disabled by default and best used as an occasional sweep, since it can’t see reflective calls, but it’s great for a spring cleaning.

A whole bunch of existing cops got sharper too, either catching things they used to miss or backing off where they used to nag:

• Lint/DuplicateMethods now catches duplicates that live in different files - the same method defined twice across two files was previously invisible to it. If you’re deliberately redefining a method (a monkey patch, say), the self-alias trick (alias foo foo right before the redefinition) signals your intent and keeps things quiet.
• Lint/ConstantReassignment likewise catches a constant that’s reassigned in another file, not just within the current one.
• Lint/MissingSuper no longer nags you about a missing super when the index can prove that none of the class’s ancestors actually defines initialize - in that case super would only reach the no-op Object#initialize. This is the one that makes those AllowedParentClasses lists mostly unnecessary; RuboCop figures out your abstract base classes on its own now.
• Lint/ConstantResolution used to be so noisy it was practically unusable without a pile of Only/Ignore configuration. With the index it reports only genuinely ambiguous constants - ones that resolve differently through the surrounding nesting than they would fully qualified - which finally makes it practical to turn on.
• Lint/InheritException now spots classes that inherit from Exception indirectly, through a parent class defined elsewhere in your project.
• Style/Documentation accepts a reopened class or module as documented as long as any of its definition sites carries a doc comment, so you’re not forced to repeat yourself at every reopening.
• A cluster of cops learned to stop producing false positives once they can see the whole picture: Style/MissingRespondToMissing accepts a respond_to_missing? defined in another reopening of the class; Style/StaticClass leaves alone classes that are subclassed elsewhere; Style/RedundantConstantBase can now flag a redundant leading :: inside a namespace when it proves the constant resolves identically without it; and Naming/PredicatePrefix and Naming/AccessorMethodName stop suggesting renames for methods that override an ancestor defined elsewhere in the project.
• Style/ClassAndModuleChildren uses the index to make its (unsafe) autocorrection a lot more reliable - it resolves the real namespace kind (class vs module) instead of guessing, and skips compacting a definition when doing so would blow up with a NameError at load time.

And a couple of things happening under the hood are worth calling out:

• The index now always covers your whole project, regardless of which files a particular run happens to inspect. That means linting a single file reports the same cross-file offenses as a full run - no more results that depend on how you invoked RuboCop.
• If you want ancestry chains that reach into your gems to resolve too (think a model inheriting from a framework base class), the new AllCops/ProjectIndexIncludesGems option indexes your bundle’s sources as well. On RuboCop’s own repo that took the share of classes with a fully resolvable ancestry from about 20% to about 97%, at the cost of some extra memory.
• The language server got smarter about the index - it now builds it once per session and reuses it across requests, rebuilding only when you save a file, so editing a buffer doesn’t pay the indexing cost on every keystroke.

Still early days

I don’t want to oversell any of this. We’re at the very beginning of RuboCop’s cross-file journey, and there’s a lot we haven’t tackled yet. The list of checks that would benefit from a project-wide view is long, and I suspect the most interesting applications are still ahead of us. rubydex itself is young and evolving, and so is our integration with it.

But I think it’s a genuinely promising start. A year ago the idea of RuboCop catching a constant typo across files, or reasoning about a class’s real ancestry, would have been a non-starter. Now it’s a config flag away.

If any of this sounds useful, I’d love for you to give it a try - add rubydex to your Gemfile, flip UseProjectIndex on, and see what it turns up in your codebase. And please tell us how it goes. The feature is still marked experimental, and real-world feedback is exactly what we need to figure out where to take it next. Bug reports, false positives, ideas for new cross-file cops - all of it is welcome.

Big thanks to everyone who has been kicking the tires on the project index and reporting their findings. Here’s to seeing beyond a single file.

Keep hacking!