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!

I’ll start with a confession I’ve made before: I rarely use ClojureScript myself, which is a big part of why its support in CIDER has historically lagged behind Clojure’s. Every “State of CIDER” survey reminds me of this, usually in the comments section, occasionally in all caps. So in the 2.0 cycle I decided to stop feeling vaguely guilty about it and actually do something - across every layer of the stack: CIDER itself, cider-nrepl, and Piggieback.

First, a strategic decision

The most important ClojureScript change in CIDER 2.0 isn’t a feature - it’s a decision about what not to build. Some of CIDER’s most powerful tools (the debugger, enlighten, tracing, profiling) are deeply tied to JVM runtime introspection, and porting them to ClojureScript would be a massive effort with a poor cost/benefit ratio. Rather than keeping them in eternal “maybe someday” limbo, we’ve explicitly scoped them as Clojure-only and focused the actual work on the things cljs users hit every day: evaluation, testing, error reporting, and clear behavior everywhere else.

That last part matters more than it sounds. Historically, invoking a JVM-only command in a ClojureScript REPL would fail in some confusing way - a cryptic error, a JVM-flavored result, or silence. Now the ops themselves report a clojure-only status, and CIDER tells you plainly that the command isn’t supported for ClojureScript. Knowing what a tool won’t do is half of trusting it.

What actually got better

• The regular test commands (cider-test-run-ns-tests and friends) now work in ClojureScript REPLs, asynchronous cljs.test/async tests included. Previously CIDER just refused, and you were stuck evaluating (run-tests) by hand like an animal.
• Expanding your own macros (e.g. ones brought in via :refer-macros) used to silently echo the form back unexpanded - a bug filed all the way back in 2017. The compiler environment is now threaded to the analyzer properly, and it just works.
• cider-nrepl now resolves the ClojureScript compiler environment through a provider chain, with a dedicated shadow-cljs provider - so the static-analysis ops keep working in a shadow REPL that never loads Piggieback.
• The new cider-tap viewer works with ClojureScript too: a runtime helper buffers tapped values and the JVM side streams them to Emacs. (Tapped cljs values aren’t inspectable - they live in the JS runtime - but you see them as they happen.)
• ClojureScript stack frames now render their ns/fn properly instead of degrading to nil/nil, and unqualified core vars resolve against cljs.core rather than falling back to clojure.core (which quietly broke things like indentation metadata).
• A recent ClojureScript on the classpath (whose Closure compiler wants JDK 21+) no longer crashes cider-nrepl at startup on an older JDK - you get a Clojure-only session instead of no session.
• Piggieback itself got a round of bug fixes in the 0.6.x/0.7.0 releases - it’s easy to forget it exists (which is rather the point of it), but it powers most cljs REPLs CIDER talks to.

The documentation kept pace too: the new full-stack Clojure + ClojureScript guide covers the two-REPLs-one-project setup that trips up nearly everyone, and the ClojureScript docs got a general refresh.

An unexpected assist

Fun aside: this is the area where AI coding agents helped me the most during the 2.0 cycle. My ClojureScript experience is limited, but between the excellent bug reports from the community and the ability to quickly prototype and test fixes against real shadow-cljs and figwheel setups, problems that had been “someone who knows cljs should look at this someday” for years finally got fixed. Make of that what you will.

What’s next

I keep pondering some form of “native” shadow-cljs support, given that shadow-cljs is what most ClojureScript users actually run these days. That’s still very much in the hammock phase, so don’t hold me to it - but the direction is clear: fewer moving parts, clearer errors, and honesty about what’s supported.

If you’re a ClojureScript user, I’d genuinely love to hear how 2.0 feels in your daily work - the feedback loop is what keeps this improving. Keep hacking!

Articles in the Series

• CIDER 2.0: Sky is the Limit
• Simplifying Session Management in CIDER
• Stepping Through Macros in CIDER
• 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

The debugger, dusted off

CIDER’s interactive debugger is one of its most impressive features and, paradoxically, one of its least reliable ones. Instrumenting arbitrary Clojure code is hard - the debugger rewrites your forms to capture locals at every step, and the corner cases are endless. Over the 2.0 cycle (and the 0.62.x releases of cider-nrepl) a whole family of long-standing instrumentation bugs got fixed:

• Record literals embedded in code survive instrumentation instead of being quietly downgraded to plain maps - which used to break protocol dispatch in anything that compiled routes or components into records (compojure users know the pain).
• defrecord/deftype inline methods no longer blow up with the infamous Unable to resolve symbol: STATE__ error - the instrumenter now sensibly skips the method bodies, which compile to real JVM methods that can’t capture debugger state. #dbg on a bare collection literal triggered the same error; fixed too. And heavily destructured argument lists used to crash instrumentation in their own special way - not anymore.
• A form too large to instrument (yes, that’s a JVM limitation - Method code too large!) now degrades gracefully: CIDER retries without local capture and tells you what happened, instead of surfacing a raw compiler error.
• Quitting a debug session uses nREPL’s interrupt machinery instead of the deprecated Thread.stop, so it keeps working on modern JDKs where Thread.stop is simply gone.

The UX got attention too. Quitting the debugger with q finally restores point to where you started the session - a request filed in 2016 - instead of stranding you at the last breakpoint. The force-step-out key works again. And all the debugger’s single-key commands are now proper named commands with a transient menu (?) listing them, so you’re never stuck trying to remember whether locals was l or L.

Tracing grew a home

clojure.tools.trace-style tracing has been in CIDER forever, but the output was always interleaved into the REPL, where it fought with your actual work. CIDER 2.0 gives traces a dedicated, live-streaming *cider-trace* buffer:

Calls fold and unfold (TAB, or F/U for everything at once), n/p move between calls, and . jumps to a function’s definition. cider-list-traced answers the eternal “wait, what did I even trace?”, and cider-untrace-all cleans the slate.

Enlighten, back from the dead

Enlighten - the mode that displays the values of locals inline as your code runs - has been in “experimental” limbo since 2016. It finally got a proper overhaul: a real test suite, fixes for the same record/deftype instrumentation bugs as the debugger (they share machinery), and - importantly - manners. You can now enlighten a single form with cider-enlighten-defun-at-point instead of flipping a global mode, and cider-enlighten-stop turns everything off at once, rather than making you re-evaluate every function in penance.

Every local and every intermediate result, right there in the buffer:

Tap into your programs

New in 2.0: cider-tap, a buffer that streams every value sent to tap> and lets you crack any of them open in the inspector with RET. tap> has quietly become the Clojure community’s favorite debugging primitive, and now you don’t need an external tool like Portal or Reveal for the basic workflow - though those remain great if you want more. (ClojureScript taps stream too; they’re just not inspectable, since the values live in the JS runtime.)

It’s println debugging, minus the println guilt.

The connective tissue

A few related quality-of-life items round out the picture: stack frames for top-level anonymous functions jump to their actual source instead of clojure.core/fn (a bug from 2020), ClojureScript frames render their ns/fn properly, and the macroexpansion tooling - a debugging tool in its own right - got a full makeover that deserves (and will get) its own article.

None of these tools is new. That’s rather the point: the 2.0 debugging story is mostly the existing tools becoming trustworthy. A debugger you don’t trust is worse than no debugger at all.

The debugging docs cover everything in detail. Keep hacking!

Articles in the Series

• CIDER 2.0: Sky is the Limit
• Simplifying Session Management in CIDER
• Stepping Through Macros in CIDER
• 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

This one is mostly about a single theme - Projectile knowing more about your project without you having to tell it anything.

Tasks you never configured

Projectile has had named tasks for a while now - you put an alist in projectile-tasks (or in your project’s .dir-locals.el) and projectile-run-task (s-p c x) offers them with completion. Useful, but there was a catch that always bugged me: the variable starts out empty, so the command did precisely nothing until you sat down and filled it in.

Meanwhile every project I work on already has its tasks written down somewhere. The npm scripts are in package.json. The Makefile targets are in the Makefile. So now Projectile just reads them:

That’s a fresh checkout with zero Projectile configuration. Out of the box it knows about npm scripts (running them through whichever package manager your lock file implies - npm, yarn, pnpm or bun), Deno tasks, Composer scripts, just recipes, go-task tasks and Makefile targets. The tool name is part of the task name, so npm:build and make:build can happily coexist and you can see at a glance where something came from.

If you don’t want this, projectile-discover-tasks turns it off. If you want more of it, projectile-task-providers is just a list of functions that take a project root and return an alist - adding support for your favorite task runner is a few lines.

A lot more project types

Projectile ships with a registry of project types, and I finally sat down and went through it properly. The result is 34 new types.

The one that surprised me most was that a package.json without a lock file next to it matched nothing at all - such a project came out as generic, with no compile or test command. That can’t have been a rare situation. Also missing: Bun, Deno, uv (which has pretty much taken over new Python projects), plain Composer, Laravel, Xcode, Flutter, Terraform, Pulumi, Helm, Ansible, just, mise, Gleam, Babashka, scala-cli, Godot, PlatformIO, and the static site generators (Hugo, Jekyll, Zola, MkDocs, Quarto).

Going through the registry also turned up three bugs that had been sitting there quietly:

• The angular type could never match anything. It listed two markers, angular.json and .angular-cli.json, and marker lists are ANDed - but a project has one or the other, never both. So the type had been dead since the day angular.json was added.
• pyproject.toml was checked before django, python-poetry, python-pipenv and python-tox. Since just about every Python project has a pyproject.toml these days, those four types effectively never matched. A Django project would come out as python-toml and lose its file kinds along with its commands.
• php-symfony required an app directory, which Symfony dropped in version 3, and a vendor directory, which only exists after someone runs composer. Modern Symfony projects weren’t detected at all.

I’ve also brought the stale markers up to date (Bazel’s MODULE.bazel, Gradle’s Kotlin DSL, Zig’s build.zig) and fixed a pile of lifecycle commands that had rotted - Symfony’s console moved to bin/ years ago, the Dart CLI absorbed pub, setup.py build is deprecated by the PyPA, and poetry projects run pytest rather than unittest discovery.

There’s a new (:any "file1" "file2") form for markers, which is what made most of this expressible as plain data rather than yet another predicate function.¹

Monorepos

If you work in a monorepo you know the problem: the repository is one project as far as git (and therefore Projectile) is concerned, but you’re usually working on one piece of it, and building or testing the whole thing is a waste of time.

Projectile now understands that a directory holding a manifest of its own is a subproject. projectile-find-file-in-subproject (s-p c m f) asks which one you want and then scopes file completion to it:

And every lifecycle command has a subproject variant now - s-p c m c compiles, s-p c m t tests, s-p c m r runs, and so on. They use the project’s own command and simply run it in the nearest subproject, which is exactly what workspace-aware tools like Cargo, npm and Maven need in order to scope their work.

There were subproject compile and test commands before this release, but they only looked for the marker of the project’s own type, which meant they were useless in a polyglot repository - a Rust crate sitting under a package.json project was invisible to them. Now the markers come from every registered project type, so it works regardless of what the repo looks like from the top.

Two commands for looking at a project

projectile-dashboard (s-p P) summarizes the project you’re in:

Everything in there is a button, so you can jump to a file, run a task or kick off a build without leaving the buffer. It never indexes the project and only queries git when the project is a local git repo, which makes it cheap enough to use as your projectile-switch-project-action - which is exactly what I do now.

The other one is projectile-doctor (s-p H), which explains how Projectile sees the current project:

Root, which detection function found it and on which marker, the type and its marker, the indexing method and the exact command that will run, which external tools are available, the cache state, the effective ignore rules - and then a list of findings, each either ok or a concrete suggestion. It’s plain text, meant to be pasted into a bug report. Selfishly, I’m hoping this saves us both some back-and-forth in the issue tracker.

Odds and ends

A few smaller things worth knowing about:

• projectile-todos (s-p s t) collects the project’s TODO/FIXME annotations into the reviewable search buffer.
• Project-scoped bookmarks - s-p B s, s-p B j, s-p B d. They’re plain Emacs bookmarks, Projectile just scopes the completion to the current project.
• projectile-replace-undo (s-p u) reverts the last replace you applied from the review buffer, and it’s careful about it - a file whose text has changed since is reported and left alone.
• projectile-per-command-compilation-buffer gives compile, test and run separate compilation buffers, so running the tests no longer discards your build output.
• An optional Embark and Marginalia integration, wired up with with-eval-after-load so neither package becomes a dependency.

Bug fixes

Three worth calling out.

The first is embarrassing and recent: with asynchronous indexing enabled, projectile-find-file could show “Projectile is indexing” and spin forever. Projectile was waiting on the indexing process’s sentinel, and Emacs doesn’t actually promise to run one while a command sits waiting on the process. It now waits on the process itself and collects the output on its own if the sentinel doesn’t show up.² Thanks to Mike Crowe for a bug report with enough detail in it (strace output included) that I could work backwards to the cause.

The second: in CMake projects, editing the compile command at the prompt didn’t stick, and you’d get the default offered again on the next run. That was a side effect of a fix from 3.2 that made function-valued commands re-resolve on every run so the preset picker could prompt again. It threw away your edit along with the cached command. Both behaviors work now - your edit is remembered, the picker still gets to prompt.

The third one has been open since 2016. If you opened a file that git ignores, Projectile would happily add it to the file cache, and it would then keep showing up in projectile-find-file even though indexing had correctly left it out. Projectile’s own ignore rules simply don’t know anything about .gitignore, so it now asks git directly before caching a file it hasn’t seen before.

Upgrade notes

A few changes might alter what you see, so it’s worth knowing about them before you upgrade:

• Alien indexing now honors Projectile’s ignore rules, which it used to skip entirely. This means alien projects will list fewer files than before. Set projectile-alien-honors-ignores to nil if you want the old behavior.
• The ignore configuration speaks gitignore patterns everywhere now, matched the same way by every indexing method. Mostly this just works, but a leading * used to mean “at any depth” and is now a plain wildcard, so *node_modules should become node_modules.
• projectile-globally-ignored-directories now includes the build and dependency directories of the common ecosystems - node_modules, target, __pycache__, .venv, .next, .terraform and a couple of dozen more. Directories that projects sometimes do commit (vendor, dist, public, build) are deliberately not on the list.

The full changelog is here, and the manual is at docs.projectile.mx.

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

Why runtime xref wasn’t enough

CIDER has had runtime cross-referencing for a while: the cider/fn-refs op walks the loaded vars in your REPL and reports which functions reference the one at point. It’s a genuinely cool trick - the REPL literally knows your program - but as a “find usages” answer it has three structural problems:

• It only sees loaded code. Namespaces you haven’t required yet - often most of the codebase - are invisible.
• It reports functions, not occurrences. Each hit points at the caller’s definition, not the exact call site, and a function that calls yours three times shows up once.
• It’s JVM-only, so ClojureScript users got nothing.

clojure-lsp, by contrast, builds a static index of your whole project with clj-kondo’s analyzer and answers instantly, loaded or not. For occurrence-oriented questions (“show me every place this is used, so I can change all of them”), static analysis is simply the right tool. No amount of runtime cleverness fixes “the code isn’t loaded”.

The fix: search the source

So CIDER 2.0 does the obvious thing we should have done years ago: xref-find-references (M-?) now finds references by searching the project’s source files on disk. Unloaded code, cljs files, commented-out drafts - if the name occurs in the project, you’ll see the exact occurrence, in the standard xref UI you already use for everything else in Emacs. To borrow the franchise that has been handing programmers debugging metaphors for over two decades now: the runtime is the Matrix, a tidy compiled illusion of your program, and to see every place a thing is really used you sometimes have to unplug and look at the source itself.¹

Here’s the difference in one picture - the same query on orchard.misc/require-and-resolve, first in runtime mode, then in source mode:

The runtime knows about three callers - and points you at each caller’s definition. The source scan turns up all ten actual occurrences, across five files, including the ones written as misc/require-and-resolve in namespaces the REPL never loaded. That’s the gap, in one screenshot.

Now, “search the source” makes it sound like a grep, and I want to be clear that it isn’t a dumb one. Say you’re chasing orchard.misc/require-and-resolve. The search runs in three stages:

1. First CIDER asks the REPL to resolve the symbol at point to its fully qualified name, orchard.misc/require-and-resolve. The REPL is right there on the other end of the wire, so why guess when you can ask?
2. A fast first pass (ripgrep, via Emacs’ own xref-matches-in-files) finds every file that so much as mentions require-and-resolve, purely to narrow the field.
3. Then the Clojure-aware part. For each of those files, CIDER reads its (ns ...) form to learn how that file pulls in orchard.misc - aliased as [orchard.misc :as misc], brought in with :refer [require-and-resolve], or is this orchard.misc itself? - and builds a regexp that matches only the forms that file could legitimately use: the qualified orchard.misc/require-and-resolve, the aliased misc/require-and-resolve, or a bare require-and-resolve where the namespace declaration makes that valid. The requires inside the ns form are excluded, so the import line doesn’t show up as a “usage”.²

Is any of this as smart as clj-kondo’s full analysis? No - it’s ultimately a syntactic search, so an identically named var in another namespace can still sneak through as a false positive. But because it’s ns-aware rather than a blind text match, a bare require-and-resolve in some file that never requires orchard.misc (and has a require-and-resolve of its own) won’t be mistaken for yours. For the daily “where is this used?” question it turns out to be remarkably close to the real thing in practice, it requires zero extra infrastructure, and it composes with what only CIDER has: the running REPL.

That composition is configurable via cider-xref-references-mode:

• source (the default) - occurrences from the project’s files.
• runtime - the historical loaded-vars behavior.
• both - source occurrences first, plus the runtime hits the scan can’t see. And there are such hits: references generated by macro expansion leave no textual trace in your source, but the runtime knows about them. Static analysis can’t ever tell you those; your REPL can.

(There’s also cider-xref-fn-refs-in-source, C-c C-? s, when you want the source search explicitly, and outside a project the source mode gracefully falls back to the runtime search.)

Beyond find usages: the who-* family

While closing the gap, we went further and built out a whole family of SLIME-inspired cross-referencing commands under C-c C-w, most of them rendered as expandable trees:

• cider-who-calls / cider-who-is-called - the call graph, upward and downward. Expand a caller to see its callers; spelunk as deep as you like:

  

• cider-who-implements - a protocol’s implementing types (inline defrecord/deftype implementations included) or a multimethod’s dispatch values, each jumping to the implementation’s source. Multimethods are a nice case study in hybrid thinking: the method functions carry no source metadata at runtime, so CIDER locates the defmethod forms by - you guessed it - searching the source.
• cider-type-protocols / cider-protocols-with-method - the reverse lookups: what does this type implement, and which protocols declare this method?
• cider-who-macroexpands - a macro’s use sites, found via source search, because macro invocations are expanded away at compile time and the runtime literally cannot see them.

Much of this is powered by new ops in cider-nrepl (and Orchard underneath), and much of the inspiration came straight from SLIME and swank-clojure, which offered who-calls back when Clojure itself was barely out of the crib. And here’s the part I love: the whole “go read the source instead of trusting the runtime” instinct was already there in swank-clojure’s implementation. Its who-calls would find candidate callers among the loaded vars, sure, but then it went and read the actual source form of each one off disk and walked the parsed code looking for your symbol, rather than believing whatever the compiled runtime claimed. It was still anchored to loaded code - it never scanned the whole project the way CIDER 2.0 does - but the core idea, that the source on disk is the ground truth and the runtime is just a convenient approximation, predates this release by about fifteen years. Good ideas don’t expire. Sometimes nothing beats revisiting the classics.³

So do you still need clojure-lsp?

If you were running clojure-lsp primarily for find-usages - the most common answer I heard when I asked - then CIDER now covers you out of the box. If you use it for project-wide renames, unused-var linting, or editing without a REPL, carry on; those are real strengths of static analysis and CIDER doesn’t try to replicate them. The two continue to work fine side by side, and the new async eldoc even yields politely so LSP-provided docs can compose with CIDER’s.

My goal was never to “beat” clojure-lsp - it was to make a freshly installed CIDER answer the questions every Clojure programmer asks a dozen times a day, with no extra moving parts, and with the one advantage nobody else has: a live runtime on the other end of the wire.

The full story is in the navigation docs. Keep hacking!

Articles in the Series

• CIDER 2.0: Sky is the Limit
• Simplifying Session Management in CIDER
• Stepping Through Macros in CIDER
• 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

Lately I’ve been giving the Emacs side of things some attention, to bring it in line with the modern completion stack so many of us now use - Vertico, Corfu, Consult, Marginalia and friends. Two changes are worth calling out.

The first is about the symbol prompts. A number of CIDER commands ask you for a Clojure symbol when there’s nothing at point - cider-doc, cider-find-var and the like. Historically those prompts used the older completion machinery, so your completing-read UI didn’t kick in and you were left with TAB and a *Completions* buffer. There’s now cider-use-completing-read-for-symbol (off by default for now); turn it on and those prompts go through completing-read over a collection that queries the running REPL lazily as you type. Vertico, Ivy, Helm - whatever you drive completing-read with - just works, and the candidates carry their type and namespace.

The second is smaller, but I like it a lot: annotations now line up in a proper column instead of trailing raggedly after each candidate.

This comes from an affixation-function, the richer successor to the old annotation-function, so every frontend that understands it - the built-in *Completions*, Corfu, Vertico - renders the aligned version. company keeps showing its own trailing annotations, same as before.

Both changes are in the latest CIDER MELPA build and will ship in the next stable release. As always, I’d love to hear how they work out for you.

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

P.S. If you use Embark, I wrote up a fun way to act on Clojure symbols with it - documentation, jump-to-definition, inspect and so on - over on Emacs Redux.

Articles in the Series

• CIDER 2.0: Sky is the Limit
• Simplifying Session Management in CIDER
• Stepping Through Macros in CIDER
• 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

The problem: CIDER is huge

CIDER has well over 300 interactive commands. I’ll admit something I’ve said before: there are features in CIDER that even I forget exist, and I wrote half of them. For users, historically, the options for finding functionality were:

• memorize cryptic key chords (C-c C-w i, anyone?)
• grep the (very long) manual
• read the source
• stumble on a feature by accident three years in and feel robbed

That’s not great for a tool whose whole pitch is making you more productive. The Emacs answer to this problem was demonstrated years ago by Magit: transient menus, which turn every prefix into a self-documenting popup. It took us embarrassingly long to follow suit, but CIDER 2.0 finally does.

Transient everywhere

Every command group in CIDER now opens a transient menu: cider-eval-menu at C-c C-v, cider-doc-menu at C-c C-d, and likewise for test, namespace, macroexpand, profile, trace and references. A top-level cider-menu ties them all together, and even the debugger (? mid-session) and the inspector (m) got menus of their own. Jack-in and connect live in cider-start-menu at C-c C-x.

Here’s the evaluation menu, which is a good illustration of the problem the menus solve - I doubt many people knew all of this was hiding behind C-c C-v:

One design constraint was non-negotiable: your muscle memory is safe. These menus replace bare prefix keymaps, so every existing keybinding works exactly as before, at full speed - C-c C-v e still evaluates instantly, menu or no menu. And if you’d rather not see the menus at all unless you actually hesitate mid-chord, set transient-show-popup to a short delay and they’ll appear only in that moment of doubt - which is precisely when you need them.

Transient also gave us something the old keymaps never could: arguments. Menus now carry flags for the things that vary per invocation - pick a pretty-printer with --print-fn=, set test selectors with --include=/--exclude= and reuse them across runs, toggle cider-ns-refresh’s modes explicitly, pass Clojure CLI aliases at jack-in time. All those “this command behaves differently with a prefix argument” paragraphs in the manual are becoming visible checkboxes instead.

The test menu shows this nicely - set the selectors once and every run below them picks them up:

Discovery beyond menus

The menus are the headline, but the discoverability push in the 2.0 cycle went wider:

• A new keybindings reference page collects every binding in one place, and the printable refcard was brought back up to date.
• The REPL’s shouty welcome banner is gone, replaced by a one-line hint; the getting-started material now lives in a summonable reference card (C-c C-h, or the ,refcard REPL shortcut) - available when you want it, invisible when you don’t.
• CIDER now warns (once per session) when you use a deprecated keybinding, so bindings can actually be retired someday without silently breaking people. M-x cider-list-deprecated-keybindings shows what’s on the way out.
• The 1.22 cycle’s big audit already made the mode menus expose dozens of commands that were technically present but practically invisible; 2.0 builds on that foundation.
• Even cider-doctor is discoverability of a sort - it surfaces the problems in your setup that you’d otherwise discover one confusing bug report at a time.

The philosophy

If I had to compress the 2.0 discoverability work into one sentence: the features were always there; now the tool tells you about them. Documentation is where knowledge goes to be forgotten - the only reliable place to teach a user about a feature is inside the workflow itself, at the moment of hesitation. Transient menus are exactly that, and Magit proved the pattern scales to enormous command sets.

If some menu feels wrong - a missing command, a flag that should exist, a grouping that doesn’t match how you think - please file an issue. This part of CIDER is young and very much open to feedback.

The keybindings docs have the full picture. Keep hacking!

Articles in the Series

• CIDER 2.0: Sky is the Limit
• Simplifying Session Management in CIDER
• Stepping Through Macros in CIDER
• 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

You had me at js/.

– Jerry Maguire, on ClojureScript interop completion

clj-suitable 0.8.0 is out! If the name doesn’t ring a bell, that’s rather the point - clj-suitable is the small library that quietly powers ClojureScript code completion in CIDER, Calva, and pretty much anything else that talks to a cljs REPL over nREPL. Think of it as the ClojureScript counterpart to what compliment¹ does for Clojure. For years it lagged well behind its Clojure sibling, and this release is my attempt to finally close that gap - to make cljs completion, if you’ll forgive me, a touch more suitable.

This is also a direct follow-up to the Piggieback work I wrote about a couple of weeks ago. Once I had the cljs REPL plumbing back in decent shape, fixing up the completion story sitting on top of it was the obvious next move.²

The mission: catch up with compliment

Clojure programmers have had really good completion for years, thanks to compliment. ClojureScript programmers got a paler version of the same idea - the basics worked, but all the little touches that make completion feel smart were missing. My goal for this cycle was simple to state and less simple to deliver: teach clj-suitable the tricks compliment has had all along. I think we’re kind of there now.

Here’s what that means in practice, mostly borrowed straight from compliment’s playbook:

• Fuzzy matching. You no longer have to type a prefix - cs now completes to clojure.string and rkv to reduce-kv, the same subsequence matching you’re used to on the Clojure side.
• Smarter ranking. Candidates are ordered the way compliment orders them - vars from the current namespace first, then cljs.core, then everything else. The thing you actually want tends to be at the top instead of buried alphabetically.
• Local bindings. Completion now sees the bindings from the surrounding form - let, loop, fn, for, doseq and friends - including destructured ones. Type first| inside (let [{:keys [first-name]} m] ...) and you’ll get first-name, which previously you would not.
• Referred vars. Inside a (:require [clojure.string :refer [jo|]]) clause you now get join, scoped to that one namespace rather than the whole world.
• Context awareness. Special forms are only offered at the head of a list, so if, let and company stop showing up as candidates in argument position where they make no sense.

None of these are revolutionary on their own, but together they’re the difference between completion that feels like an afterthought and completion that feels like it belongs.

A bit of backstory

There’s a nice irony in chasing compliment, because for a while ClojureScript completion actually lived inside it. Back in 2019 Andrea Richiardi ported the cljs-tooling completion machinery - the same code CIDER used for cljs at the time - straight into compliment, and there was even a follow-up attempt to pull clj-suitable’s JavaScript interop completions in alongside it. (You can still spot the heritage: a few functions in clj-suitable’s current source are marked “Ported from compliment.”)

In the end we went the other way around: instead of growing compliment to cover ClojureScript, we consolidated the ClojureScript side in clj-suitable and reverted the port. That sounds like wasted effort, but it wasn’t - compliment’s pluggable custom source architecture is exactly what made the split clean. clj-suitable just registers itself as another source, so tools get Clojure and ClojureScript completion side by side without compliment having to know a thing about cljs.

Robert Krahn had started clj-suitable earlier that year for the dynamic, runtime-introspection side, and the static ClojureScript completion found its permanent home there too. In hindsight it was clearly the right call: cljs completion gets to grow (and break, and get fixed) on its own schedule, and compliment stays focused and lean. A good architecture is the kind that makes the split you didn’t plan for feel obvious after the fact.

Why ClojureScript makes this harder

Completion for Clojure is almost unfairly simple. Your code runs on the same JVM as the nREPL server, so compliment can just reflect on the live thing - real vars, real namespaces, real Java classes, all sitting in the same process. Ask a question, get an answer.

ClojureScript doesn’t get to be that lucky, because it lives in two worlds at once. The compiler is a Clojure program running on the JVM, and it’s the source of truth for namespaces, vars and their metadata - so static completion reads the ClojureScript compiler state, not your running program. But your actual program runs somewhere else entirely: a Node process, a browser tab, maybe a React Native app on a phone, reachable only across a REPL bridge. When you want to complete JavaScript interop - the methods on js/console, say - there’s nothing on the JVM to reflect on. You have to ship a bit of code across that bridge, run it in the JS runtime, and read back what a live object actually exposes.

That one fact is where all the complexity comes from. The bridge isn’t even a single thing - a piggieback-driven cljs.repl runtime evaluates differently from shadow-cljs, and clj-suitable has to speak both. The runtime can vanish under you - refresh a browser tab and the namespace you loaded is gone. And poking at a JS object to list its properties can have side effects, because a property getter is just code that runs. (If you’ve ever wondered why clj-suitable is so careful to only evaluate things that genuinely look like interop, that’s why.)

So a completion request that looks like one operation from the editor is really two very different machines under the hood - one reading compiler state on the JVM, one evaluating code in a JS runtime you don’t control. Here’s the whole picture:

  editor (CIDER / Calva)
     |   complete: prefix + context
     v
  nREPL server (one JVM) - cider-nrepl + clj-suitable
     |
     +-- static ---> compliment + clj-suitable's cljs source
     |               reads the ClojureScript compiler state
     |               (namespaces, vars, locals, keywords) - stays on the JVM
     |
     +-- dynamic --> only for JS interop forms
                        |   eval introspection code across the REPL bridge
                        v
              piggieback (cljs.repl)   or   shadow-cljs
                        |
                        v
              Node / browser / React Native  (the JS runtime)
              suitable.js-introspection reads a live object's
              properties and methods, and sends them back
     |
     v
  candidates from both paths, merged and returned to the editor

Two paths, one answer. Clojure completion has only ever needed the top half of that diagram.

Dynamic completion, tightened up

That dynamic path is the fiddly one, and it’s where this release did most of its sanding. The interop completion already worked - (.| js/console) would offer you log, warn and the rest - but it had some rough edges:

• Completing interop no longer clobbers your REPL history. Poking at (.| js/some-obj) used to quietly overwrite *1/*2/*3 with the introspection result; now your last real value stays put where it belongs.
• The introspection namespace is loaded once per session instead of on every single completion request. On a Node REPL that’s a needless round-trip gone from every keystroke.
• The browser-runtime path got hardened. I chased down a couple of long-standing “no completions in the browser” reports, stood up a real headless-Chrome integration test to reproduce them, and fixed a lurking crash along the way. (The short version of the investigation: the old failures came from an inlined build that current CIDER no longer produces, so most of you were never affected - but now there are tests making sure it stays that way.)

The full changelog has everything that didn’t make the highlights.

One more thing

0.8.0 gets the headline, but it stands on the 0.7.0 release from a week earlier, which did the unglamorous groundwork: modern dependencies (ClojureScript 1.12, compliment 0.8.0, shadow-cljs 3.x), a move from CircleCI to GitHub Actions, a tools.build-based build, and - crucially for my sanity - actual integration tests that drive real Node and browser runtimes instead of trusting things to work.

Actually, I only thought about improving how clj-suitable works when I started to update its dependencies and CI setup.

Epilogue

No sufficiently useful system can be both complete and consistent.

– Kurt Gödel, subtweeting every autocomplete ever

If you use CIDER, you don’t have to do anything to get any of this - it’ll ship to you as part of the upcoming CIDER 2.1. Calva and other nREPL-based tools that depend on clj-suitable will pick it up on their own schedule.

As always, this stands on the shoulders of others. Huge thanks to Alex Yakushev, whose compliment is both the benchmark I was chasing and the source of a good chunk of these ideas; to Andrea Richiardi, who did much of the early work bridging ClojureScript completion and compliment; and to Robert Krahn for creating clj-suitable in the first place and giving me such a solid foundation to build on.

Is any of this complete? Of course not - completeness is a horizon, not a destination, and of all people a completion library should be the first to admit it (see the gentleman up top). But clj-suitable suits ClojureScript a good deal better than it did a month ago, and that was rather the point.

Keep hacking!

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!