It started with a bug report

Shortly after the revival post, someone reported that pressing c i in the workspace view - “inspect this captured value” - printed Def'd as $s/* and then… nothing. The fix turned out to be a one-liner: Sayid was calling a CIDER function whose signature changed years ago, and nobody had noticed since. Which tells you everything about how many people were actually using that command.¹

The one-liner was easy, but the report got under my skin. If the inspector integration could sit broken for years, what else about Sayid was quietly hostile to anyone trying it for the first time? So I sat down and did a proper UX audit of the Emacs client, wrote down everything that made me wince, and 0.8 is the result.

Here’s the current state of affairs in one take - trace, run, explore:

Catching up: 0.6 and 0.7

Before we get to the UX work, a quick recap of the two releases I never got around to announcing (the revival post covered things up to 0.5).

Sayid 0.6 rebuilt inner tracing - the mode that records every intermediate expression inside a function - on top of tools.analyzer.jvm. The old implementation re-read your source and rewrote raw forms, with special cases for individual macros; the new one works off the analyzed AST. That killed the long-standing bug where an inner-traced try/catch would swallow exceptions, along with the per-macro special-casing that made the old instrumenter so fragile.

Sayid 0.7 made the trace itself data. sayid.data/trace-data returns the recorded call tree as plain Clojure data with the live captured values, and tap-trace! sends it to tap>, so you can explore a recording in Portal or your data tool of choice. It also added sayid.golden - capture a run’s call tree as a baseline, then assert future runs still match it, which is a surprisingly pleasant way to pin down the behavior of gnarly legacy code before refactoring it.

The highlights

Now, the 0.8 goodies. The full list is in the changelog, but here’s what I’m most excited about:

• There’s a proper entry point now: C-c s pops up a transient menu (sayid-menu) that groups the commands along Sayid’s core loop - trace something, run your code, explore the recording - and shows you how much is traced and recorded right now, or what’s missing (a REPL, the middleware) when you’re not connected. The menu uses the same key sequences as the classic prefix map, so your muscle memory keeps working, and sayid-use-menu brings the plain keymap back if popups aren’t your thing.

• sayid-trace-fn (C-c s t t) is the new “just trace this” command. You no longer need to know what inner and outer traces are before you can trace your first function - the default does the right thing, and you can graduate to the fancier variants later.
• Empty views teach instead of scolding. Opening the workspace before anything was recorded used to greet you with an error; now you get the buffer anyway, with a short walkthrough of how to get data into it. The first five minutes with Sayid should no longer require reading the manual.
• The commands talk back like a human. Tracing a function now tells you what happened and what to do next (“Outer-traced acme.checkout/subtotal - run some code, then C-c s w shows what was recorded”), and trying to enable a trace that doesn’t exist tells you the actual problem instead of pretending everything went fine.
• The workspace tree is now the one view to rule them all: on any call you can inspect a captured value in CIDER’s inspector (c i - yes, it works now), def it to a var for REPL poking (c d), pretty-print it (c p), or copy an expression that reproduces the call (c r). C-c s f - show the recorded calls of the form at point - renders there too.
• A pile of small courtesies that add up: tracing a function no longer steals your window with a popup, g refreshes the Sayid buffers like every other Emacs buffer, and resetting the workspace asks before irreversibly dropping your traces and recording.
• The client and the middleware now tolerate version skew - if your deps.edn pins an older Sayid jar than your Emacs package expects, things degrade politely instead of erroring in strange ways.
• The Emacs client now requires CIDER 2.0, which let me drop a bunch of compatibility shims and lean on the new cider-tree-view throughout.
• And the README finally shows the tool instead of just describing it - screenshots and the GIF above included. A picture of a call tree is worth a thousand words about one.

Upgrading notes

Nothing here should break a working setup, but two things are worth knowing. The Emacs package now requires CIDER 2.0 (released earlier this week), so they’ll need to be upgraded together. And C-c s now opens the menu instead of acting as a bare prefix - every old key sequence still works exactly as typed, but if you prefer the old silent prefix, set sayid-use-menu to nil. A few commands got more consistent names (sayid-trace-fn-outer and friends); the old names live on as obsolete aliases.

Onward

When I wrote the revival post I asked people to kick the tyres and tell me what feels rough. This release is what acting on that feedback looks like, and it’s exactly the kind of contribution I need more of - a two-line bug report turned into the biggest usability overhaul in the project’s history. So thanks to everyone who has been trying out the revived Sayid, and please keep the reports coming on the issue tracker.

[mx.cider/sayid "0.8.0"] is on Clojars, the Emacs package is on MELPA, and tracing your first function is now a single C-c s t t away. Give it a spin!

Keep hacking!

Replace, but with a preview

projectile-replace has always been one of those commands that technically worked, but that I never quite trusted. It walks the project file by file with query-replace, asking you about every match with no way to see the big picture, and once you start there’s no graceful way out. I’ve been promising myself a better story there for years (that’s #1924, if you’re keeping score at home).

3.2 finally delivers it. projectile-replace-review (s-p R) prompts for a search string and a replacement, gathers every match across the project into a *projectile-replace* buffer, and shows you a per-match preview of exactly what’s about to change. Every match can be toggled on or off, and ! applies just the enabled ones - in any order, whenever you’re ready. Here’s the whole flow, start to finish:

The matches are gathered in Emacs Lisp rather than by shelling out to grep, so projectile-replace-regexp-review honours full Emacs regexp syntax (yes, including \_<foo\_> and capture groups in the replacement), and the preview reflects the exact text that will be edited - including unsaved changes in buffers you already have open. The apply step is equally paranoid: files are edited bottom-up so earlier edits can’t shift later matches, open buffers get a single undo step, and buffers modified since the scan are skipped rather than clobbered.

The results buffer is a little workbench of its own - you can toggle case sensitivity (c), flip between literal and regexp matching (x), keep or flush matches by line or by file (k/d/K/D), and export everything to a grep-mode buffer (e) if you’d rather finish the job with wgrep. And both reviewers scan the project asynchronously, so a big search no longer freezes Emacs - matches stream in as they’re found and you can bail out at any point.

Search gets the same treatment

Once the replace reviewer existed, the obvious next question was “can I have this without the replacing part?”. You can. projectile-search-review (s-p s R) collects every match for a term into a read-only *projectile-search* buffer, grouped by file, with the matched spans highlighted:

It shares the replace reviewer’s navigation and filtering, and pressing r hands the current search over to the replace reviewer, carrying along the term and settings and prompting only for the replacement. So “look first, replace later” is now a single keystroke, not a re-do.

My favourite touch: when rg is installed, a literal search rides ripgrep and streams matches in near-instantly even on huge projects (customizable via projectile-search-use-ripgrep). The regexp variant and the replace reviewer always use the portable Emacs Lisp scan, so the preview you act on is always the real thing.

A tab per project

The bonus feature: projectile-session-mode, a global minor mode that gives each project its own tab-bar tab. Switch to a project and Projectile either selects its existing tab (with the window layout you left there) or opens a fresh one named after the project. Sessions can also persist across restarts - s-p w s saves a project’s layout and buffers, switching to the project can restore it automatically, and projectile-session-restore-all brings your whole working set back after a restart, each project in its own tab.

I’ve long envied the “workspace per project” workflows people build with tab-bar and a handful of hooks, and now Projectile just does it out of the box. It’s opt-in, so nothing changes unless you enable the mode.

Odds and ends

A few smaller things that shipped alongside the headliners:

• The reviewable search/replace learned whole-word matching - toggle it with w in the results buffer, or default it with projectile-search-whole-word.
• projectile-dispatch picked up matching switches - --word and --case-sensitive seed the reviewable search/replace, the same way --regexp already did for the other search commands.
• All the search prompts now share one consistent format that shows the tool that will actually run and the symbol-at-point default up front. No more guessing whether you’re about to invoke grep or ripgrep.
• Projectile’s prompts now advertise the right completion metadata category per command, so marginalia annotates candidates properly (buffers get buffer annotations, projects get file ones) and embark can act on them. With vertico and marginalia the built-in commands look downright fancy now:

• Function-valued lifecycle commands (say, a CMake preset picker) are re-invoked on every run instead of having their first result frozen in the command cache - an old gotcha that bit CMake users in particular.

Wrapping up

No breaking changes this time, and nothing to migrate - the full list of changes is in the changelog, as always.

More importantly, 3.2 completes - for now - the arc I embarked on with 3.0. Looking back at the whole 3.x series, the mission boils down to three things:

• make Projectile’s internals faster, simpler and more robust
• modernize the UX (async everything, the dispatch menu, and now reviewable search and replace) and give people more reasons to prefer Projectile
• replace hardcoded behavior with mechanisms - backend registries, file kinds, named tasks, session serializers - that you can bend to your own workflow in a few lines of config

All three boxes feel properly ticked at this point, so the summer release burst is probably winding down.² Projectile is in the best shape it’s been in years, and I’m having more fun working on it than I’ve had in a long time. Huge thanks to everyone who reported issues and tested the new reviewers while they were taking shape!

Keep hacking!

The Dream

CIDER has had macroexpansion support practically forever - C-c C-m expands the form before point into a dedicated buffer, a feature we inherited spiritually from SLIME. It works, but it has always felt a bit… detached. The expansion lives in another buffer, divorced from the code you’re reading, and for deeply nested macros you end up bouncing between buffers trying to keep your bearings.

Emacs Lisp hackers have long had something nicer: macrostep, a brilliant little package that expands macros in place - right where they sit in your code - one step at a time, and collapses them back when you’re done. I’ve wanted a Clojure version of this for years. CIDER 2.0 finally ships one.

Standing on shoulders, not on top of them

I’m hardly the first person to want this. The idea of bridging CIDER and macrostep goes back to at least 2016, where a proof of concept wired up macrostep’s extension hooks to CIDER by injecting a couple of helper functions into your REPL and shuttling forms back and forth as strings. Later, macrostep-geiser - a Scheme-oriented macrostep backend - grew CIDER support as well, and SLIME itself ships a slime-macrostep contrib built on the same extension API. So the hooks were there, the hacks existed, and I could have blessed one of them and called it a day.

I opted for a clean, from-scratch implementation in CIDER instead - mostly to provide the best possible experience for Clojure programmers, without the compromises the bridges had to make. macrostep’s extension API was designed around Emacs Lisp’s happy circumstances, and Clojure violates most of them:

• macrostep-expand-1-function must be synchronous. That’s fine when expansion is an elisp function call; it’s less fine when it’s a network round-trip to an nREPL server. (CIDER has been busy removing exactly this kind of blocking call lately - asynchronous eldoc being the poster child.)
• The API traffics in forms - elisp data structures. But Clojure code isn’t elisp data: keywords, reader tags, #() lambdas and namespaced maps have no faithful elisp representation, so every bridge ends up round-tripping code through strings and hoping the quoting survives. The 2016 proof of concept literally did (format "(expand-once '%s)" form), which should make anyone a little nervous.
• macrostep-print-function expects the client to print and fontify the expansion. In CIDER the server does the printing - that’s how we get namespace tidying (when instead of clojure.core/when), print-option handling and metadata display for free. A client-side printer would have to reimplement all of that, badly.

There’s also a less technical reason: lately I’ve grown rather averse to adding third-party dependencies to CIDER. A dependency is a bet on someone else’s continued enthusiasm, and such bets sometimes go bad - tellingly, macrostep itself spent a stretch unmaintained and now lives in a GitHub org literally named “emacsorphanage” (it has since found a new maintainer, but the point stands). CIDER is 14 years old and intends to stick around; over that kind of horizon, owning ~600 lines of overlay code is cheaper than adopting someone else’s semi-abandoned package. So we kept macrostep’s brilliant UX ideas and its familiar keybindings, and left the coupling behind.

cider-macrostep

The entry point is cider-macrostep-expand (C-c M-m e). Put point after a macro form, invoke it, and the form is replaced inline with its one-step expansion, highlighted so you can tell what’s expansion and what’s your code:

(when-let [x (fetch-thing)]
  (process x))

;; C-c M-m e =>

(let [temp__5825__auto__ (fetch-thing)]
  (when temp__5825__auto__
    (let [x temp__5825__auto__]
      (process x))))

From there you’re in cider-macrostep-mode, where the further-expandable sub-forms are underlined, n/p hop between them, e (or RET) steps into one, and c/q collapse one level or everything back to the original code. Your buffer is never actually modified in a way that sticks - collapse everything and it’s exactly as it was.

Here’s the whole flow in motion - expand, step into a nested macro, collapse back to the original code:

A couple of touches I’m particularly fond of:

• Every distinct gensym in the expansion gets its own color, so you can finally track where that temp__5825__auto__ flows through the expanded code. Once you’ve seen a for expansion with colorized gensyms, you won’t want to go back:

• E (cider-macrostep-expand-all) fully expands the form in one step, for when you don’t care about the journey.
• b (cider-macrostep-expand-in-buffer) runs the same stepping session in a dedicated popup, leaving the source buffer untouched - handy when you’re in someone else’s code and feel uneasy about inline rewrites, however temporary.

The classic buffer got some love too

The traditional macroexpansion buffer wasn’t neglected either: it grew a header line showing the active expander and display options, n and t cycle namespace display and metadata in place, g re-expands with the latest macro definition, and freshly expanded forms pulse briefly so your eye lands in the right place.

The expansion commands also got more talkative: pointing them at an unresolved symbol now tells you whether the namespace simply isn’t loaded yet (evaluate the buffer!) or you’ve got a typo, instead of silently doing nothing.¹

Why bother?

Macros are the part of Clojure people are most likely to describe as “magic”, and the standard advice - “just macroexpand it” - has always carried a hidden tax: the expansion of any non-trivial macro is a wall of gensyms and nested let*s that’s genuinely hard to read cold. Stepping through the expansion one level at a time, in place, with the gensyms color-coded, turns that wall into something you can actually follow. I did not expect macro debugging to become fun, and yet here we are.

All the details are in the macroexpansion docs. Give it a try the next time a macro surprises you - and keep hacking!

Unfinished business

When I announced clj-refactor.el 3.0 back in 2021, I opened with a confession - we had failed to deliver the main objective of that release, namely restoring the dependency hot-loading that JDK 9’s module system broke. Well, better late than never: cljr-hotload-dependency is back in 4.0, reimplemented on top of clojure.tools.deps, and it even accepts deps.edn-style coordinate maps alongside the classic Leiningen vectors.¹

I’ll also be honest about the bigger picture, as I was back then: clj-refactor spent most of the intervening years in maintenance mode, while clojure-lsp became the default refactoring engine for much of the community. That hasn’t discouraged me, though - it clarified what clj-refactor should be. The project now has a proper roadmap that spells out where things are headed (spoiler: a static analysis index and closer ties with CIDER), and 4.0 is the first big step in that direction.

The highlights

The changelog for 4.0 has over 40 entries, but here’s what I’m most excited about:

• There’s a new clj-refactor-menu - a transient menu of every command, grouped by category (bound to hh under your prefix, e.g. C-c C-m hh). It mirrors the classic two-letter mnemonics, so it doubles as a way to finally learn them. It replaces the old hydra-powered menus, which allowed us to drop the hydra dependency.
• Project-wide refactorings are no longer a leap of faith. cljr-rename-symbol, cljr-change-function-signature and cljr-inline-symbol now show you their edits as a diff and touch nothing until you confirm, and the new cljr-undo-last-refactoring (ur) reverts the last applied refactoring across every affected file in one step.
• The heavyweight commands went asynchronous. Renames, signature changes and file renames used to freeze Emacs while refactor-nrepl analyzed the project - now they return immediately, show a spinner in the mode-line, and finish when the analysis does. Cold-cache runs on big projects are dramatically more pleasant.
• cljr-change-function-signature grew up: it can add and remove parameters now (not just reorder and rename them), it understands multi-arity functions, and a long-standing parsing bug that broke it against recent CIDER releases is fixed.
• cljr-slash (the magic requires feature) learned a neat trick: entries in cljr-magic-require-namespaces can carry an :artifact coordinate, and when the namespace isn’t on your classpath, typing json/ will offer to add the library to your project and hotload it on the spot.
• A bunch of commands now work without a running REPL. cljr-slash and cljr-add-missing-libspec fall back to the static alias table, cljr-clean-ns falls back to sorting the ns form, and cljr-remove-let and the #(...) -> (fn ...) promotion are handled purely on the Emacs side. Refactoring your requires before the REPL is up is no longer a paper cut.
• Everything got snappier. Artifact lists and libspec suggestions are cached client-side (the latter matters because cljr-slash fires on every / keystroke), and the startup cache warming now actually populates the cache the interactive commands read from.
• clj-refactor now talks to refactor-nrepl using namespaced op names (refactor/clean-ns and friends), with a graceful fallback for older middleware versions. The companion refactor-nrepl 3.14.0 release also hardened the AST analysis and made find-usages noticeably faster on projects with many macros.
• The dependency diet continued: multiple-cursors, hydra and inflections are gone, along with a pile of aliases that had been deprecated since 2.3.0. clj-refactor is a much leaner package than it used to be.
• And a long tail of quality-of-life fixes - cljr-describe-refactoring now opens the wiki page in your browser instead of scraping HTML, the dependency commands give clear errors instead of raw search failures, and clojure-ts-mode users get a working offline ns sort and proper setup docs.

Upgrading

4.0 is a major release and it does come with breaking changes: the minimum requirements are now Emacs 28.1 and CIDER 2.0, the long-deprecated 2.3.0-era command aliases are gone (use the clojure-* equivalents that live in clojure-mode these days), and the legacy namespace-aliases code path in cljr-slash was removed along with its three configuration options. On the middleware side you don’t need to do anything if you use cider-jack-in - refactor-nrepl 3.14.0 gets injected automatically, and older versions keep working thanks to the op-name fallback. Most setups should upgrade without touching a thing, but do skim the changelog if you have a heavily customized configuration.

Five years later

Reading the 3.0 announcement again, I wrote back then that we wanted to show “we haven’t reached the limit of what one can do with a purely (mostly?) REPL-powered approach to refactoring”. I still believe that, and 4.0 is hopefully some evidence. The roadmap has the rest of the plan - including making the analysis fast and robust enough to erase the reasons people reach for other tools - and with CIDER 2.0 out the door I finally have some cycles to spend here.

Huge thanks to everyone who contributed to clj-refactor and refactor-nrepl over the years, to Clojurists Together for supporting the broader CIDER ecosystem, and to everyone who kept filing issues during the quiet years - they shaped most of what shipped in this release.

In the REPL we trust!

Truth be told, I meant to write this article back when the work landed in CIDER 1.22,¹ but I was so busy wrapping up CIDER 2.0 that I’m only getting to it now, as part of this series. Better late than never, right?

A bit of history

Back in the pre-history of CIDER (before 0.18), there were no sessions at all - just connections, and a very simple rule: commands went to the most recently used connection that made sense for your buffer. Crude? Sure. But it mostly worked OK, and - crucially - everyone understood it.

CIDER 0.18 replaced this with Sesman-based session management. Sessions grouped related REPLs together and could be linked to projects, directories and buffers, which made multi-project workflows a lot more robust. Shortly afterwards, in 0.19, we introduced the concept of friendly sessions (I wrote about it back in Happy New CIDER!) - sessions that CIDER would infer for buffers that had no explicit links, so that things Just Worked without any setup.

I’ll be honest: I was never a big fan of the friendly-session concept. It was one more piece of terminology for users to learn (“linked? friendly? current?”), and its behavior felt a bit like magic in some cases - your buffer would get associated with some REPL, and it wasn’t always obvious why that one. Magic is great when it works and infuriating when it doesn’t, and session inference worked… most of the time.

The breaking point

Over the years the friendly-session matching logic quietly accumulated complexity. To decide whether a session was friendly to your buffer, CIDER would check whether the file was on the session’s classpath (fetched over nREPL and rescanned regularly), and, failing that, try to match the buffer’s namespace against the namespaces loaded in the REPL. Clever! Also: slow, hard to predict, and hard to debug.

Then it got worse. The matcher runs on a very hot path - the mode-line needs to know the current REPL, so it effectively ran on every redisplay. At some point a change made it call file-truename over every classpath root on each of those runs, and Clojure buffers without a connected REPL became visibly laggy (#3933 - if you’ve ever felt CIDER make plain editing sluggish, that was probably it).

The performance bug was fixable in place. But while staring at the code I realized the classpath scan never needed to be there at all. Friendly sessions were originally introduced for essentially one use case: making cider-find-var (M-.) into a dependency’s source land in a buffer that still talks to your project’s REPL. That’s a navigation problem, not an inference problem.

The fix: less magic, more predictability

So #3935 restructured the whole thing around two simple rules:

• When you jump to a dependency’s source via a CIDER navigation command, the buffer gets pinned to the session you came from. Evaluation, completion and friends keep targeting that REPL, no inference required.
• For everything else, a session is friendly to a buffer simply when the buffer’s file lives under the session’s project directory. That’s one cheap string comparison instead of a classpath scan.

That’s the entire model now. It killed the redisplay lag, dropped a couple of nREPL round-trips we used to make on every connection, and - more importantly to me - you can now predict what CIDER will do without consulting the source code.

Is the new behavior dumber than the old one? Slightly, and deliberately so. It’s still smarter than the pre-0.18 “last used connection” rule - project boundaries are respected, and dependency buffers follow the session you were working in. The one thing you lose is auto-association for files outside the project that you open by non-CIDER means (say, a plain find-file into a jar). For those you can link a session explicitly (C-c C-s p and friends) - or use the next thing.

Default sessions: opting out of inference entirely

While I was in the area, I also added (back) a default session facility - old-timers may remember that the pre-sesman connection era had a similar notion. If you’d rather have absolute predictability than any cleverness:

M-x cider-set-default-session

Pick a session, and from that point on every REPL lookup - evaluation, completion, documentation, the lot - goes to it, regardless of which buffer you’re in. M-x cider-clear-default-session reverts to the normal project-based association. No linking, no friendliness, no inference - just “always use this one, until I say otherwise”.

The two styles, side by side

Say you’re working on two projects at once - a backend and a frontend:

• ~/code/backend with a Clojure REPL
• ~/code/frontend with a shadow-cljs (ClojureScript) REPL

With the default (inference-based) behavior, things flow like you’d hope:

• You open ~/code/backend/src/api/handler.clj and evaluate a form - it goes to the backend REPL, because the file lives under that session’s project directory.
• You press M-. on a ring var and land in a jar - the dependency buffer is pinned to the backend session, so completion and evaluation keep working against the backend REPL.
• You switch to ~/code/frontend/src/ui/views.cljs - commands now target the frontend REPL. No links, no configuration, no surprises.

Now the contrasting style. Suppose you’re spending the afternoon debugging the backend, but you keep bouncing between projects, scratch buffers, and random files scattered around your disk, and you want all of it to hit the backend REPL:

• M-x cider-set-default-session RET backend
• Every buffer - the frontend sources included - now talks to the backend REPL. What you evaluate is what you get, everywhere.
• When you’re done: M-x cider-clear-default-session, and the project-based behavior above kicks back in.

The full dispatch pipeline (pinned buffer → default session → linked/friendly session → REPL type filter → recency) is documented in detail in the session management docs, including an ASCII flowchart I’m unreasonably proud of. See in particular the sections on friendly sessions and the default session.

Closing thoughts

Session management is one of those areas where the “smart” solution and the good solution turned out to be different things. Seven years of friendly sessions taught me that users don’t actually want their tools to be clever - they want them to be predictable, and fast, and clever only when the cleverness is cheap and explainable in one sentence. “Your project’s files use your project’s REPL” passes that bar; “your buffer matches some session’s classpath” never did.

More posts about the notable changes in CIDER 2.0 are coming soon. Until then - keep hacking!

The preview post covered the big themes in detail - the transient menus, the call-graph browsers, cider-macrostep, the revamped tracing and enlighten, the ClojureScript improvements - so I won’t rehash all of that here. Instead I’ll focus on what changed between the preview and the release, and on the bigger picture of what CIDER 2.0 is actually about.

What CIDER 2.0 is about

Looking back at the (enormous) changelog, the release boils down to four themes:

• Tackle some ambitious ideas that had been lying dormant for ages - inline macro stepping, rich (content-type) results, source-aware cross-referencing. Some of the issues closed by this release were filed the better part of a decade ago.
• Polish the “understand your code” toolbox - the debugger, the macroexpansion facilities, tracing, enlighten, the stacktraces and the cross-references all got a serious amount of love.
• Make the whole CIDER experience more consistent and discoverable - transient menus everywhere, one tree-view widget shared by all the browsers, and a naming cleanup that brought a bunch of stragglers in line.
• Fix old annoyances - the friendly-session complexity that 1.22 started taming (remember the redisplay lag fix and default sessions?), the find-references gaps, the flaky SSH tunnels, the confused stdin handling.

Notice what’s not on that list - a pile of shiny new features. There are a few genuinely new things in 2.0, of course, but the heart of this release is that most of CIDER’s important features got overhauled (tastefully, I hope) or made more robust and faster. After 14 years you accumulate a lot of good ideas with rough edges; 2.0 is me going over them with fine-grit sandpaper.

What landed after the preview

Quite a lot, as it turns out - the last two weeks were busy. The headliners:

• Rich results are now on by default. Evaluate something that returns an image and it renders inline; a result that points to external content (a file, a URL) gets a [show content] button that fetches it only when you press it. HTML renders as formatted text, URLs are clickable. This works for regular C-x C-e-style evaluations too, not just in the REPL (configurable via cider-eval-rich-content-destination). Fun fact: content-type support was added way back in 0.17, disabled in 0.25 after it got a bit overzealous with the fetching, and the interactive-eval part was requested in 2018. Better late than never, right?
• The transient story got finished. The debugger and the inspector now have menus of their own (? and m respectively), and many menus grew argument flags - pick a pretty-printer per invocation, set test selectors once and reuse them across runs, toggle the refresh modes, pass aliases at jack-in. As before, your muscle memory is safe - the menus only help when you pause.
• There’s a new cider-doctor command that checks your Emacs setup and your active session for common problems (version mismatches, stale byte-code, leftover obsolete config) and produces a copy-pasteable report. My hope is that it will make “CIDER doesn’t work” bug reports a thing of the past - or at least give us something to look at when they arrive.
• Pending evaluations now show an animated spinner overlay right at the form you’re evaluating, instead of a spinner in the mode-line of a REPL buffer you probably can’t even see.
• The debugger got dusted off properly: quitting a debug session finally restores point to where you started - an issue filed in 2016 - the force-step-out key works again, and cider-nrepl 0.62 fixed a batch of instrumentation bugs (records surviving instrumentation, clear errors for forms too big to instrument, and a few crashes).
• Stdin handling got a long overdue overhaul - input prompts are routed to the session that actually asked for input, cancelling a prompt now interrupts the evaluation (instead of quietly letting it continue), and C-c C-d sends EOF for code that reads until end of input.
• Clicking a stack frame for a top-level anonymous function now jumps to the actual source instead of clojure.core/fn - a bug from 2020 - and ClojureScript frames render their ns/fn properly.
• A big consistency pass over the options: the REPL history browser is now cider-history, the inline-result options became a coherent cider-eval-result-* family, and the six per-buffer auto-select options collapsed into a single cider-auto-select-buffer. Every old name keeps working as an obsolete alias, so nothing breaks.
• And a long tail of robustness work - a slow memory leak on the eldoc/completion path, cider-classpath on Windows, formatting no longer corrupting multi-line strings, theme-aware colors for the nREPL message log, and plenty more of the same ilk.

The documentation also got restructured to be more approachable - there’s a proper quickstart now, a keybindings reference page, dedicated pages on using CIDER alongside clojure-lsp and clojure-ts-mode, and a guide for full-stack Clojure + ClojureScript projects. The manual has grown organically for over a decade, and it showed; hopefully finding things is much easier now.

Upgrading

Despite the big scary version number, upgrading should be uneventful. All the renames ship with obsolete aliases, the transient menus preserve the classic keybindings, and the only removals are commands that had been no-ops for years. The one bit of muscle memory you may need to adjust: cider-macroexpand-all moved from C-c M-m to C-c M-m a, as C-c M-m is now a prefix for all the macroexpansion commands. If anything feels off after the upgrade, M-x cider-doctor is your friend.

Fourteen years later

CIDER 0.1 (well, nrepl.el 0.1) was released on July 10th, 2012 - fourteen years (and five days) ago.² I’ve been reflecting on this a lot lately. Fourteen years is an eternity in our line of work - entire ecosystems have come and gone in that time - and yet here we are, still innovating, still improving, still moving forward. I dare say CIDER 2.0 is the strongest release in the project’s history, and it’s certainly the one I’ve enjoyed working on the most.³

None of this would have been possible without the people and organizations who have supported the project over the years - everyone who contributed code, reported issues, wrote about CIDER, answered questions, or backed the project financially. A special thanks to Clojurists Together for their long-standing support, and to everyone who took the snapshot for a spin after the preview post and shared feedback - several rough edges got filed down because of you.

So, go play with CIDER 2.0! Kick the tires, explore the menus, crack open some values in the inspector, step through a macro or two. And if CIDER makes your work a little nicer every day, consider supporting its future development

• that’s what keeps CIDER and friends going.

Where to from here? The sky is the limit. The REPL is the inspiration. The best is always yet to come…

Keep hacking!

What’s Drawbridge, anyway?

In case you’ve never come across it: Drawbridge is an HTTP transport for nREPL, packaged as a humble Ring handler. You mount it in your web application, and suddenly you can REPL into that application over plain HTTP(S) - no open socket, no special network setup, just another route in your app:

(ns my-app.repl
  (:require [drawbridge.core :refer [secure-ring-handler]]
            [ring.adapter.jetty :refer [run-jetty]]))

(defn -main [& _]
  (run-jetty (secure-ring-handler :token (System/getenv "DRAWBRIDGE_TOKEN"))
             {:port 8080 :join? false}))

Chas Emerick created it way back in 2012, in the golden era of Heroku-style PaaS platforms.¹ The problem it solved was very real: those platforms gave your application exactly one way in - HTTP on port 80/443 - and nREPL speaks bencode over a raw socket. If you wanted a REPL into your production app (and of course you did, this is Clojure), you needed the REPL to ride on HTTP. Drawbridge was that ride. The name suddenly makes a lot of sense, doesn’t it? It’s the thing you lower to let people into the castle.

When I took over nREPL’s maintenance in 2018, Drawbridge came along as part of the broader ecosystem cleanup and moved to the nrepl GitHub org. It got a couple of releases back then (0.2.0 and 0.2.1), and after that… silence. Seven years of it.

The bridge that never got you across

Truth be told, Drawbridge never really delivered on its promise. Let me try to explain why.

First, security. A Drawbridge endpoint is remote code execution as a service - that’s the whole point - but the project shipped with no authentication story at all. “Bring your own middleware” was the official answer, and the number of people who got that right on the first try was, I suspect, not large. Exposing your production REPL on the public internet with hand-rolled auth is the kind of thing that keeps security teams up at night, and rightfully so.

Second, the tooling never came. CIDER, Calva, and practically every other nREPL client connect over a plain socket with a host and a port. Drawbridge connections only worked through lein repl :connect and hand-written clients - so the audience was limited to people willing to REPL without their editor. That’s a tough sell.

Third, the transport itself was long-polling: the client keeps asking the server “anything for me yet?” over and over. It worked, but it always felt a bit sluggish, and it could flood your server with polling requests in the process.

Given all that, the community sensibly routed around the problem. If you had SSH access to the box, tunneling the nREPL port (ssh -L) was simpler and more secure than anything Drawbridge offered. And nREPL itself eventually grew native TLS support, which covered another chunk of the use cases. Between those two, “secure remote nREPL” mostly stopped meaning “HTTP”.²

But the original niche never went away. Plenty of environments still give you HTTP ingress and nothing else - PaaS platforms, container services, corporate networks where the only thing allowed through the firewall is 443. In those places SSH tunnels and TLS sockets aren’t options, and Drawbridge remains the only game in town. It just needed to stop being a liability there.

Dusting it off

The modernization happened in two waves. A quiet 0.3.0 earlier this year dragged the foundations into the present - current nREPL, Ring and friends, Clojure 1.10+, Java 17+, a real test suite and CI. The fun stuff landed now, in 0.4, and it goes straight after the three problems above - reach, trust and speed.

• The headline feature is the bridge (drawbridge.bridge) - a small local process that presents a plain nREPL socket on localhost and relays everything to a remote Drawbridge endpoint. This single thing unlocks the entire nREPL ecosystem: CIDER, Calva, rebel-readline, anything that speaks bencode can now reach a Drawbridge endpoint. It even writes a .nrepl-port file, so cider-connect picks it up automatically.
• Security is finally built in, and it’s opt-out rather than opt-in. secure-ring-handler gives you a complete endpoint with bearer-token authentication (constant-time comparison, naturally) in one form, and it flat-out refuses to create an unauthenticated endpoint unless you explicitly pass :insecure true. Exposing an open REPL should be a deliberate act, not an oversight.
• There’s a brand-new WebSocket transport that replaces long-polling with real server push - output streams to your REPL the moment it’s produced. The bridge picks it automatically for ws(s):// URLs, and the server pings idle connections so aggressive proxies (looking at you, 55-second router timeouts) don’t sever your session mid-thought.
• The old HTTP transport is still there as the lowest-common-denominator fallback, and it got some love too - including a fix for a subtle session-affinity race that had been quietly lurking in the client since the beginning.
• The bridge CLI tries to be a good citizen: it reads the token from DRAWBRIDGE_TOKEN (command-line arguments leak via ps), validates its arguments, has a --help, and when it can’t reach the remote endpoint it tells you why right in your REPL instead of silently dropping the connection.
• There’s a deps.edn now, so you can run the bridge straight from a git coordinate without installing anything.
• A couple of ancient issues got closed along the way, including the “Drawbridge clobbers my Ring session” bug that had been open since 2018. (It had actually been fixed for a while - now there’s a regression test proving it.)

The end-to-end experience today looks like this. On the server - the secure-ring-handler example above. On your machine:

$ export DRAWBRIDGE_TOKEN=<token>
$ clojure -Sdeps '{:deps {nrepl/drawbridge {:mvn/version "0.4.0"}}}' \
    -M -m drawbridge.bridge --url https://my-app.example.com/repl

…and then cider-connect (or lein repl :connect http://localhost:7888, or whatever you fancy). Your editor neither knows nor cares that there’s HTTP in the middle.

Where you might actually use it

A few scenarios worth trying:

• REPL into an app on a PaaS or container platform that only exposes HTTP(S) - the original 2012 use case, finally with your editor along for the ride.
• Debugging a staging environment from behind a corporate firewall that only lets 443 through.
• Ops-style poking at a running service where provisioning SSH access would be a bureaucratic adventure, but adding one authenticated route is a code review away.
• The WebSocket transport within your own infrastructure, simply because server push makes for a much nicer remote REPL than polling ever did.

To be clear - if you do have SSH access or can expose a TLS socket, those remain excellent options, and I’m not here to talk you out of them. Drawbridge is for everywhere they don’t reach.

Feedback, please!

Drawbridge spent so long in hibernation that I’ve genuinely lost track of who still uses it and for what. If you take 0.4 for a spin - or if you looked at it years ago and bounced off - I’d love to hear about it on the issue tracker: what works, what doesn’t, what’s missing. I have some ideas of my own for where to take it next (smarter session handling is high on the list), but I’d much rather steer by real use cases than by my own guesses.

Big thanks to Chas Emerick for building Drawbridge (and nREPL!) in the first place - reviving a well-designed project is a pleasure, even 14 years later. And big thanks to Clojurists Together, Nubank, and all the other organizations and people supporting my Clojure OSS work - none of this would be happening without you.

In the REPL we trust! Keep hacking!

The past two months were super productive. I had a lot of inspiration during this period and I managed to tackle a lot of long-standing ideas and issues across the entire nREPL/CIDER ecosystem. Funnily enough, I also managed to grow the ecosystem with a couple of brand new projects, but more about those later.

The big highlights from my perspective:

• CIDER 1.22 is out
• CIDER 2.0 is essentially ready and needs more user testing
• Sayid is reborn
• Two brand new projects saw the light of day: port and neat
• Piggieback 0.7.0 is out (and Weasel got modernized while I was in the area)
• clj-refactor and refactor-nrepl got some love as well

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

CIDER

CIDER 1.22 (“São Miguel”) landed in mid-June, wrapping up the 1.x series. Its main features:

• a registry for jack-in tools, so third parties can plug new build tools and Clojure dialects into cider-jack-in
• a “default session” escape hatch from sesman’s project-based dispatch
• keyword-argument versions of the low-level request APIs, alongside a proper decoupling of the nREPL client layer from CIDER’s UI

It also fixed a long list of small annoyances: severe editor lag in unlinked buffers, several TRAMP and SSH tunnel problems, request id leaks, and a bunch of broken menu entries.

• CIDER 1.22.0
• CIDER 1.22.2 (plus a quick 1.22.1 fixing a docs site problem)

Right after that I switched the development version to 2.0 and most of the planned work is already done. The headline items so far:

• transient menus for all the command groups (plus new menus for the debugger and the inspector)
• inline stepwise macroexpansion
• SLIME-style call graph browsers (who-calls, who-implements and friends)
• source-based find-references
• a tap> buffer and a dedicated trace buffer
• namespace load-state indicators
• the revival of rich content in the REPL

That last one deserves a special mention: evaluation results that are images now render inline out of the box, and file/URL results offer their content on demand, six years after the feature had to be disabled over its safety problems. There was also a big cleanup pass: consolidated configuration options, the REPL history browser renamed to cider-history to end a long-standing naming clash, theme-aware faces instead of hardcoded colors, refreshed docs and a regenerated refcard. CIDER 2.0 is available from MELPA snapshots and I’d love for more people to take it for a spin before the final release.

cider-nrepl

Lots of cider-nrepl releases, driving the CIDER work above:

• cider-nrepl 0.60.0 added the ops backing the new protocol exploration commands (cider/who-implements, cider/type-protocols, cider/protocols-with-method).
• cider-nrepl 0.61.0 brought ClojureScript test support, a ClojureScript macroexpansion fix, formatting that honors the project’s cljfmt configuration, and a pprint backed by orchard.pp.
• cider-nrepl 0.62.0-alpha1 and 0.62.0-alpha2 hardened the content-type and slurp middleware (URL scheme allowlist, size caps, graceful fetch errors) and cleaned up the response protocol, which is what made it safe to turn rich content on by default in CIDER 2.0.

Along the way the project’s build was migrated from Leiningen to tools.deps, which required a new MrAnderson release (see the blog posts below).

Orchard

Orchard, the library that powers much of cider-nrepl’s functionality, kept pace:

• Orchard 0.42.0 and Orchard 0.43.0 continued the inspector polish, added symbol classification to orchard.meta, a programmatic listener API for the tracer, and protocol/multimethod introspection in orchard.xref. The project also moved to tools.deps and its CI now covers JDK 26.

Sayid

Sayid, the omniscient Clojure debugger, had been dormant for years and I finally gave it the revival it deserved:

• Sayid 0.2.0 was the big modernization pass: new mx.cider/sayid coordinates, a documented nREPL middleware API, a consolidated op surface (37 ops down to 26) and fixes for the most annoying Emacs client breakages.
• Sayid 0.3.0 followed with usability work: no more frozen Emacs during the reload workflow, simpler query commands and help buffers generated from the keymaps.

port

port is a brand new project I started in May: a minimalist Clojure interactive programming environment for Emacs, built on prepl instead of nREPL. It went from nothing to three releases in the course of the month:

• port 0.1.0
• port 0.2.0
• port 0.3.0, which added eldoc with active argument highlighting, a wire-level message log for debugging and a roughly 10x speedup in handling large prepl responses.

I don’t have any particular plans for the future of this project - it was just something that I wanted to experiment with for a while. I see it as an interesting option for people looking for some middle ground between inf-clojure and CIDER.

neat

neat is the other new arrival: a small, language-agnostic nREPL client for Emacs. neat 0.1.0 has the essentials in place: a pure-elisp bencode codec, a comint-based REPL, and a source-buffer minor mode with eval, completion, eldoc, xref and doc lookup, tested against Clojure, Babashka and Basilisp. It’s early days, but it’s a nice testbed for exercising the nREPL protocol outside CIDER.

This project also means I’ve dropped any plans to try to make CIDER a language-agnostic development environment. Going forward CIDER will focus only on Clojure-like languages, and everything else will be covered by neat.

Piggieback and Weasel

The nREPL org saw some ClojureScript-flavored action:

• Piggieback 0.6.2 and Piggieback 0.7.0. The 0.7.0 release makes load-file evaluate the editor’s buffer contents instead of re-reading from disk, tears down ClojureScript REPLs when their sessions close (no more leaked Node processes) and surfaces ClojureScript status in the describe response.
• Weasel 0.8.0 modernized the WebSocket REPL: the client now uses the platform’s native WebSocket, so it runs in any modern JavaScript runtime (browsers, Node 22+, Deno, Bun, workers), and the minimum requirements moved to Clojure/ClojureScript 1.12.

I also backfilled proper GitHub releases for the historic tags of both projects, so their release history is finally browsable.

Improving the ClojureScript support in CIDER has long been a major objective for me, and these small changes were some initial steps in that direction.

refactor-nrepl and clj-refactor

refactor-nrepl got three releases: 3.12.0, 3.13.0 and 3.14.0, the last one making the AST-based indexing much faster and more reliable. clj-refactor.el received a round of maintenance on master as well, and will get a new release after I wrap up the work on CIDER 2.0.

I’m still pondering the future of both projects, as I plan to move the most useful refactor-nrepl features (those that don’t carry a lot of complexity) to CIDER and cider-nrepl eventually, and I’m not sure that the flagship AST-powered refactorings are very competitive these days (compared to clojure-lsp and static project-wide analysis a la clj-kondo in general).

I’ll write a bit more about this and I’d certainly appreciate more feedback from the users of clj-refactor on the subject. It’s funny that I’ve been maintaining the project for ages, but I’ve never really used it (mostly due to its brittleness in the past). I think I managed to address some of the biggest problems recently, but perhaps this happened too late and the project has lost its relevance by now.

Blog posts

I wrote a few articles related to the work above:

• Port: a minimalist prepl client for Emacs
• neat: a language-agnostic nREPL client for Emacs
• nREPL Forever
• CIDER 1.22 (“São Miguel”)
• MrAnderson 0.6
• CIDER 2.0 is Brewing…
• nREPL and ClojureScript: Demystifying Piggieback
• Sayid Redux

Wrapping up

Big thanks to Clojurists Together, Nubank and the other organizations and people supporting my Clojure OSS work! I love you and none of this would have happened without you. Sadly, the amount of financial support my projects receive has eroded massively over the past 4 years and I’ve kind of lost hope that this negative trend will eventually be reversed. It was never easy to maintain many popular OSS projects, but the job certainly hasn’t got any easier or more rewarding in recent years…

Overall, a super productive two months. Hopefully the next two are going to be just as productive, although I have to admit I’ve plucked most of the low-hanging fruit already. Then again, I’ve said this many times in the past, so one never knows…

Three days apart, yes. There’s a story there. A big chunk of what’s in 3.1 was originally meant for 3.0, but 3.0 was already turning into a monster of a release and I decided to cut it into two, so I’d actually be able to reason about each of them. So think of 3.1 less as “the next release” and more as “the second half of 3.0 that I was too scared to ship all at once”.

There was also a bit of calendar mischief involved. I really wanted a release on the 1st of July - that’s July Morning, which is a bit of a thing here in Bulgaria¹ - and then another one on the 4th of July. Partly because it’s the 250th US Independence Day, and partly because it happens to be my wedding anniversary. When else am I going to get a round number like that to line up? So here we are.

Unlike 3.0, 3.1 has no breaking changes. Nothing was removed, no command or option changed its name. What it does instead is knock out a pile of long-standing ideas and feature requests, most of which pull in the same direction: making Projectile leaner under the hood and a lot more extensible from your own config.

Projectile learns what you actually work on

projectile-find-file now ranks the files you visit most often and most recently at the top of the completion list. It’s the kind of thing you don’t notice until you go back to a Projectile without it and suddenly your muscle memory is off. It works with any completion UI (Vertico, the default one, whatever) and under every indexing method, and it’s on by default. If it’s not your thing, set projectile-enable-frecency to nil.

Named project tasks

The six lifecycle commands (compile, test, run, …) were never enough for real projects, which tend to accumulate a dozen little “run this incantation” commands. So there’s projectile-tasks now - an arbitrary set of named commands you can attach to a project. The nice part is you can put them in .dir-locals.el and share them with your team through the repo:

((nil . ((projectile-tasks . (("lint"   . "make lint")
                              ("deploy" . "make deploy STAGE=prod"))))))

Then s-p c x (projectile-run-task) prompts you for a task and runs it, with a prefix argument if you want to tweak the command first. This one subsumes about four separate feature requests I’d been staring at for years.

Finding files by kind

This is my favourite one. Lots of frameworks organize files into well-known kinds - Rails has models, controllers, views and helpers; Django has models, views and urls; and so on. Projectile can now describe those kinds declaratively, and it gives you two commands for free: s-p j to jump to a file of a particular kind, and s-p J to hop between related files (from a model to its controller to its views and back).

The best part is that it’s not hardcoded. Rails and Django ship out of the box, but the whole thing is driven by a :file-kinds entry on the project type, so you can teach Projectile about your own framework’s layout in a few lines. This is the “more extensible” theme in a nutshell - I’d much rather ship a mechanism than a hardcoded list.

Running the test at point

If you’re on Emacs 29+ with tree-sitter, s-p c . runs just the test your cursor is in, rather than the whole suite. It figures out the enclosing test from the parse tree and builds the right command. pytest, go test and jest are supported out of the box, and - you guessed it - you can register rules for other test runners yourself.

Other-window and other-frame, the Emacs way

Instead of a small army of -other-window/-other-frame command variants, there are now s-p 4 4 and s-p 5 5 prefixes, modeled exactly on Emacs’s own C-x 4 4 / C-x 5 5. Press s-p 4 4 and the next Projectile command opens its buffer in another window - even commands that never had a dedicated variant. The old commands still work, of course.

More solid under the hood

A few things got quietly sturdier:

• projectile-invalidate-cache has always been Projectile’s most notorious footgun. If you opt into projectile-auto-update-cache-with-watches, Projectile watches your project and keeps its file cache in sync as files come and go, so you rarely have to think about invalidation at all. It’s off by default and deliberately conservative - when in doubt it just rebuilds.
• The glob patterns in your dirconfig now follow .gitignore-style rules, and they behave identically under native and hybrid indexing. This kills a whole family of “why is this file showing up” bug reports that go back the better part of a decade.
• Project and project-type detection now probe marker files with a single directory listing instead of a stat per marker, which turns dozens of sequential round-trips into one over TRAMP.

I should have done all of those a long time ago, but better late then never, right?

Wrapping up

There are no breaking changes, but a handful of defaults and behaviors did shift (auto-discovery is on by default now, for one), so give the Upgrading to Projectile 3.1 guide a quick read before you upgrade. The full list of changes lives in the changelog, as always.

With 3.1 out the door, Projectile is basically where I always wanted it to be. I’ve got a few ideas for follow-up releases, but the pressure is off - this is the release where the big items I’d been carrying around for years finally got done. Another win for my burst-driven approach to maintaining my projects: nothing happens for a while, and then a whole lot happens at once.

Keep hacking!

What’s dead can’t die

There’s a running joke that Projectile is obsolete now that Emacs ships project.el out of the box. I’ve heard it many times, and I even wrote about it when Projectile turned 10 - it’s obviously hard to compete with a built-in package, as it has a home-field advantage you can never match.

But here’s the thing. If it’s really true that Projectile is dead and everyone has moved on to project.el, then that’s oddly liberating. What’s dead can’t die, right? If there are no users left to upset, I can finally go wild with my wildest ideas and stop worrying about breaking the workflows of Projectile’s (non-existent) users. And that’s more or less the spirit in which I approached 3.0 - I stopped being quite so precious about backwards compatibility and just did what I felt was right for the project.

(Turns out there might still be a user or two out there after all, so do skim the upgrade notes below. Sorry in advance!)

The highlights

There’s a lot in this release - well over a hundred entries in the changelog - but here are the highlights I’m most excited about:

• projectile-dispatch (bound to s-p m) is a new transient menu that mirrors the command map, so you no longer have to remember every keybinding. It also exposes command modifiers as switches, so you can toggle a regexp search, start a fresh shell, invalidate the cache, or open a result in another window/frame right from the menu.
• Projectile can now index a project asynchronously, in a background process, so a cold projectile-find-file no longer freezes Emacs while it walks a huge tree. The building blocks are public, so external tools can drive Projectile’s indexing asynchronously as well.
• There’s a new (optional) projectile-consult integration built on those async data sources. Its finder streams candidates into the minibuffer as the project gets indexed, instead of blocking until indexing is done, while still honouring your VCS and indexing configuration.
• The various search commands got folded into a single projectile-search, backed by a small, extensible backend registry. It ships grep, ripgrep and ag backends out of the box, and you can register your own (deadgrep, consult-ripgrep, whatever you fancy) in a few lines.
• The shell, REPL and terminal commands got the same treatment - one projectile-run with shell, eshell, ielm, term, vterm, eat and ghostel backends, plus a seam to plug in your own.
• The indexers got a thorough going-over - batched stat calls, single directory listings instead of dozens of file-exists-p probes, smarter caching. It all adds up, and it really shows over TRAMP, where every needless round-trip used to hurt. I think that 15 years later I’ve finally solved Projectile’s infamous performance issues over TRAMP!²
• I finally removed a pile of features that had outlived their usefulness - the single-key Commander (superseded by the dispatch menu), the idle timer, projectile-browse-dirty-projects, and all of the built-in tags support (xref and LSP do this far better nowadays).
• The minimum supported Emacs is now 28.1. That let me drop a heap of compatibility shims and finally make transient a proper dependency instead of an optional extra.
• Projectile is a better project.el citizen now - it implements more of the protocol (project name, buffers, ignores), so tools built on top of project.el behave correctly in Projectile-managed projects.
• I also dropped the legacy ido/ivy/helm completion systems - these days everything rides on the standard completing-read, so Vertico, Consult and friends just work. ido fans are the one group that has to lift a finger: install ido-completing-read+ (the package formerly known as ido-ubiquitous) and turn on ido-ubiquitous-mode, and ido will drive Projectile’s prompts just like before.
• And there’s a pile of smaller quality-of-life additions - subproject compile/test for multi-module projects (c m c / c m t), a %p placeholder for the project name in command strings, projectile-add-and-switch-project, jumping back to the most recent project, and more.

Upgrading

3.0 is a major release for a reason - there are breaking changes. The minimum Emacs version is now 28.1, several long-deprecated commands and options are gone, and a couple of keybindings moved around. I’ve written a dedicated Upgrading to Projectile 3.0 guide that walks through everything and how to adapt your config. Most setups will keep working untouched, but please give it a read before you upgrade.

Fifteen years later

As I said back when Projectile turned 10 - it’s always hard to compete with built-in packages. Still, I’m genuinely proud that 15 years in, Projectile is still here and, hopefully, still relevant to at least some of you. It remains one of my favourite projects and the one I reach for every single day.

Huge thanks to everyone who has contributed code, reported bugs, written extensions, or simply used Projectile over the years - none of this would exist without you. I really hope 3.0 isn’t the end of the innovation for Projectile, and that it’ll keep surprising and delighting its users for years to come.

Keep hacking!