Neocaml 0.9: A Better REPL, Dune/Opam Completion, and More Robustness

2026-06-24T10:00:00+03:00
It’s been a couple of months since the last neocaml release, and the reason is simple — for a while there I was genuinely out of ideas. Back when I shipped 0.6 I declared (again!) that I was done with new features, and this time I almost meant it. But ideas have a way of creeping back in, and 0.9 turned out to be a meaty release. Here are the highlights.
A much nicer REPL experience

The biggest chunk of work went into the REPL (toplevel) integration. I’m well aware that the OCaml toplevel isn’t terribly popular with seasoned OCaml developers — most of them reach for a proper build and a debugger instead. But I think newcomers get a lot of mileage out of a REPL, and (no surprise to anyone who’s followed my work) I’m a Lisper at heart with a real soft spot for interactive development. Clojure and Emacs Lisp spoiled me, and I want OCaml beginners to taste a bit of that too.
So, what’s new:
A dedicated REPL per project. The REPL buffer is now named after its project (e.g. *OCaml: myproject*), and the send commands route to the current buffer’s project REPL. You can have several projects running side by side without them stepping on each other.
Choose your toplevel. The new neocaml-repl-flavor lets you pick between ocaml, utop, and dune-utop. Set it globally, or per project via .dir-locals.el:
class="highlight">
1
((neocaml-mode . ((neocaml-repl-flavor . dune-utop))))
The active flavor shows up in the REPL’s mode line, so you always know what you’re talking to.
Send a phrase and step. C-c C-n (neocaml-repl-send-phrase-and-step) sends the phrase at point to the REPL and moves on to the next one — perfect for walking through a file top to bottom while you experiment.
#require from Emacs. neocaml-repl-require loads a findlib package into the running toplevel without you having to type the directive by hand.
Restart on demand. neocaml-repl-restart kills and restarts the toplevel when things get into a weird state.Completion for Opam and Dune, no LSP required
This one I’m particularly happy with. .ml/.mli files have ocaml-lsp-server to lean on for completion, but the auxiliary file formats have no language server at all. That’s exactly the kind of gap neocaml is meant to fill, so both neocaml-dune-mode and neocaml-opam-mode now ship a completion-at-point backend.
In a dune file you get completion for stanza names, the field names valid for the enclosing stanza, and library names inside libraries/pps fields:
(library
 (name my_lib)
 (libraries str re|))   ; <- completes both your own libraries and installed findlib ones
The library candidates combine your project’s own libraries with whatever’s installed in the active Opam switch. And it’s switch-aware — if there’s a project-local switch (an _opam/ directory), neocaml detects it and queries it via opam exec --, without any configuration on your part. The results are cached per project, so it stays snappy.
In opam files you get completion for field and section names, and package names inside depends/depopts/conflicts (sourced from opam list):
depends: [
  "dune" {>= "3.0"}
  "cmd|"   ; <- completes to cmdliner and friends
]
Both backends can be toggled off via neocaml-dune-complete-libraries and neocaml-opam-complete-packages if you’d rather not have them.
Robustness improvements
A good chunk of this release is the unglamorous but important work of making things just behave correctly:
Character literals and quoted strings at the syntactic layer. Tree-sitter fontifies '"', '(', and {|raw "strings"|} correctly, but the syntax table underneath was getting confused — which broke forward-sexp, delete-pair, and electric-pair-mode around those constructs. The fix was a good old syntax-propertize-function. I wrote up the whole story over on Emacs Redux in Tree-sitter Modes Still Need a Syntax Table, if you’re into mode-writing internals.
project.el integration. A directory with a dune-project file is now recognized as a project root (even without version control), _build/ and _opam/ are ignored, and compile-command defaults to dune build in dune projects.
There’s more in there too — ocamlformat integration (C-c C-f), clickable URLs and bug references in comments, a font-lock level selector, and richer menus across the modes.
OCaml 5.5 support, and the ABI 14 balancing act
OCaml 5.5 was released on June 19th, so this felt like a good moment to ship 5.5 support in neocaml. The ocaml and ocaml-interface grammars now track tree-sitter-ocaml v0.25.0, which brings the 5.5 grammar along with it.
There’s a wrinkle here that’s worth explaining, because it’s shaped the last few releases. A tree-sitter grammar gets compiled into a parser that speaks a particular ABI version, and Emacs can only load parsers up to the latest ABI supported by the libtree-sitter it was built against — it’s not the Emacs version itself that sets the ceiling. In practice a lot of Emacs 30 builds out there (notably Homebrew’s on macOS) are linked against tree-sitter 0.24, which tops out at ABI 14; you need an Emacs built against tree-sitter 0.25+ to load ABI 15 grammars. The trouble is that the tree-sitter 0.25 CLI now generates ABI 15 parsers by default, so any grammar regenerated with current tooling produces something those builds simply can’t load — you install it and it just errors out. Emacs 31 will ship with newer tree-sitter and make ABI 15 the common case, but it’s not out yet. (This isn’t a neocaml problem as such; it’s been biting tree-sitter modes across the ecosystem.)
After a few users ran into exactly this, I’ve made a deliberate decision: stick to ABI 14 grammars until Emacs 31 is widely available. That effort started a couple of releases back — in 0.8.1 I lowered the ABI requirement from 15 to 14 across the opam, dune, and ocamllex modes, switched the menhir recipe to tmcgilchrist/tree-sitter-menhir, and pinned ocamllex back to v0.24.0, all of which target ABI 14 (#42). 0.9 extends that policy to the core OCaml grammars.
The catch with v0.25.0 is precisely that it generates an ABI 15 parser. Happily, the 5.5 grammar didn’t actually need any ABI 15 features — the bump rode along with the CLI upgrade — so an ABI 14 regeneration of the very same grammar is a drop-in. Big thanks to 314eter, the tree-sitter-ocaml maintainer, for cutting a v0.25.0-abi14 tag for exactly this purpose (#141). The one snag was that tagging normally triggers releases to NPM, crates.io, and PyPI, so I sent a small PR to skip publishing for ABI-suffixed tags (#142), and the tag followed. neocaml now pins both grammars to it.
Roadmap and docs
If you’re curious where neocaml is headed, I’ve started keeping a ROADMAP.md with ideas and guiding principles (short version: tree-sitter first, lean on the LSP stack for .ml/.mli, and own the auxiliary modes that have no language server). The project also has a proper documentation site now at neocaml.org, so there’s a real home for the details beyond the README.
Give it a Try
As always — update from MELPA, play with it, and let me know how it goes. The full list of changes is in the 0.9.0 release notes. Bug reports, feature requests, and pull requests are all welcome on GitHub.
That’s all from me, folks! Keep hacking!


Emacs loves AsciiDoc
2026-06-11T09:00:00+03:00
Regular readers know I have a soft spot for AsciiDoc – I’ve written about it more than once, and it’s the markup behind the documentation of most of my bigger OSS projects (CIDER, nREPL, Projectile, RuboCop). It hits a sweet spot Markdown never quite reaches: rich enough for proper technical writing (admonitions, includes, real tables, cross-references), without dragging in the full ceremony of something like DocBook.
There was just one problem, and it nagged at me for years: editing AsciiDoc in Emacs was never much fun.
Background
For years the only real option was adoc-mode, and it was showing its age. The font-locking was uneven, it predated modern Asciidoctor syntax, and it lagged far behind what markdown-mode (and org-mode) offered. So I’d catch myself reaching for Markdown in situations where AsciiDoc was clearly the better tool – not because Markdown was better, but because markdown-mode was. That always bugged me.
Eventually the itch got bad enough that I did something about it. Back in 2023 I took over maintenance of adoc-mode, which had been dormant for years, and set myself a clear goal: get it to feature parity with markdown-mode. More recently I also started a brand-new asciidoc-mode built on top of tree-sitter. The target for both is the same – AsciiDoc support in Emacs that’s on par with Markdown, and ideally not far off from Org.
Less is more, unless it’s modes
Why two modes? They scratch slightly different itches:
adoc-mode is the classic, regexp-based mode. It works on any reasonably modern Emacs, has no external dependencies, and now ships a pile of interactive features (markup commands, list editing, image preview, tempo templates).
asciidoc-mode is the newer, tree-sitter-based mode. It leans on a real grammar for robust, accurate highlighting and good performance in large documents. It’s leaner by design, and it needs Emacs 30.1+ with tree-sitter.¹
If you want the kitchen sink on any Emacs, reach for adoc-mode. If you’re on a recent Emacs and want highlighting backed by an actual parser, try asciidoc-mode. Pick whichever fits your setup – both are actively maintained.
Recent developments
I’ve spent a good chunk of the past month bringing both modes to a place I’m genuinely happy with, and they’re now mostly feature-complete as far as I’m concerned. Some highlights:
Modern AsciiDoc, not legacy AsciiDoc.py. Both modes now track the modern Asciidoctor spec – something I’d wanted to do for a while. +text+ and ++text++ are treated as passthroughs rather than monospace, curved-quote syntax ("`text`") is recognized, the block ID shorthand [#id] is supported, checklists are highlighted, and the menus and templates dropped a bunch of deprecated AsciiDoc.py leftovers.
More uniform font-locking. I went through the faces in both modes and aligned them with markdown-mode and org-mode: bold renders as plain bold, emphasis as plain italic, structural markup (delimiters, list markers) fades into the background, and dedicated semantic faces cover metadata, URLs, footnotes, highlights, and roles. Switching between Markdown and AsciiDoc no longer feels jarring.
Navigation that actually works. Clickable cross-references and links, an xref backend over anchors, context-aware completion, and – for adoc-mode – cross-file Antora cross-reference resolution.
Tooling integration. Asciidoctor-backed preview/export and a Flymake checker that reports parser errors inline.
Native code-block fontification. [source,LANG] blocks in asciidoc-mode are highlighted using the language’s own major mode, just like in markdown-mode and org-mode. adoc-mode had added support for this a while back.
Getting asciidoc-mode where I wanted it also meant sending a few fixes upstream to the tree-sitter-asciidoc grammar it builds on. A grammar-backed mode is only as good as its grammar, so some of the work happened a layer below Emacs. If you’re curious about that side of things, I wrote up the broader experience in building Emacs major modes with Tree-sitter.
Give it a try
If you’ve been avoiding AsciiDoc in Emacs because the tooling wasn’t there – I get it, that was me too. But the situation is genuinely different now. Grab adoc-mode or asciidoc-mode, point it at one of your .adoc files, and see how it feels.
And please share your feedback. Both projects are at the stage where real-world usage surfaces the rough edges I can’t see myself. Bug reports, ideas, and PRs are all very welcome on the respective issue trackers.
Together we can make AsciiDoc a first-class citizen of the Emacs ecosystem!²
That’s all from me, folks! Keep hacking!
Also, I really wanted to name something asciidoc-mode. ↩︎
Afterwards we’ll aim for world domination, of course. ↩︎


nREPL Forever
2026-05-20T09:00:00+03:00
Last week I announced Port, a small prepl client for Emacs. That post focused on Port itself, but writing it left me with the itch to do a follow-up on the bigger picture, because the socket REPL / prepl story is one I’ve been meaning to write up for years.
If you’ve been around Clojure long enough, you remember the chatter. Socket REPL landed in Clojure 1.8 (January 2016), prepl in Clojure 1.10 (December 2018), and for a couple of years there was a steady stream of posts, tweets, and Slack threads to the effect of “this is what we should be building tools on. nREPL is on the way out.” Some serious people put their weight behind that idea, and some of them went and built tools to prove it.
Now it’s 2026 and we can take stock.
Sky is the limit
The pitch was good. Socket REPL is just the Clojure REPL exposed on a TCP port. prepl wraps it with a structured printer so the bytes coming back are EDN-tagged maps (:ret, :out, :err, :tap) instead of a human-readable prompt. Both ship with Clojure itself. No external server library, no middleware, no third-party namespaces. You start a JVM, you bind a port, you’re done.
The intellectual case for moving off nREPL had been made by Rich Hickey himself, most clearly in a March 2015 clojure-dev post that’s worth reading in full. Rich didn’t actually attack nREPL by name in that message. What he did was argue carefully for what a REPL is: a thing that reads characters, evaluates forms, prints results, and loops, with those streams available to user code so that things like nested REPLs and debuggers compose naturally. The money line:
While framing and RPC orientation might make things easier for someone who just wants to implement an eval window, it makes the resulting service strictly less powerful than a REPL.
His proposal, in the same post, was that tools should open multiple connections to the running program: one for the human-facing stream, and dedicated channels for IDE operations. The socket REPL (which landed in 1.8 the following January) and prepl (which arrived in 1.10) were the official implementation of that worldview.
A handful of editor projects took the cue and built clients:
Tutkain for Sublime Text
Chlorine for Atom
Conjure for Neovim (in its early Rust incarnation)
Clojure-Sublimed by Nikita Tonsky
a steady drip of smaller experiments around unrepl, propel, and friends
It was real momentum. If you were following Clojure tooling in 2018-2020, it genuinely felt like nREPL might be the past, and the future would be some combination of socket REPL plus a thin self-installing protocol on top of it. You can find a fair number of “RIP nREPL” hot takes from that period if you go looking.
Reality Check
I went and surveyed each of those projects recently while working on Port. The pattern is depressingly consistent:
Tutkain started on prepl. In November 2021, its v0.11 release explicitly stopped using prepl message framing and switched to a hand-rolled EDN-RPC protocol that Tutkain boots onto the raw socket REPL by sending it a base64-encoded blob. The new protocol has request ids, op dispatch (:eval, :lookup, :completions, :test, :apropos, :interrupt, …), and server-managed thread bindings. In other words: Tutkain grew into nREPL, just spelled differently.
Chlorine never used prepl directly. It used socket REPL plus an unrepl-style upgrade blob. Its author’s successor project, Lazuli, abandoned the whole approach in favor of nREPL. The post-mortem is worth reading and is fairly blunt: tools that attempted prepl went back to nREPL because, honestly, it’s simply better.
Conjure had a prepl client in its early Rust days. The current Lua/Fennel rewrite ships only an nREPL client. The author’s reasoning in the release notes was that nREPL “has complete ecosystem adoption and brilliant ClojureScript support.”
Clojure-Sublimed technically still talks to a raw socket REPL, but only after sending it an EDN-printing prelude that upgrades the REPL to a structured protocol of tonsky’s own design. His post on the topic is one of the most thoughtful pieces I’ve read on Clojure REPL design, and his conclusion is roughly: the bare socket REPL is more useful than prepl because you can install your own protocol on top of it. Which is true. But notice that everyone who reached that conclusion ended up reinventing the same wheel: ids, ops, request/response correlation, completion support, lookup, interrupts. You know, the things nREPL has had since 2010.
So the trajectory looks roughly like this:
Editor decides nREPL is too heavy or an undesirable external dependency and starts on prepl.
Editor discovers prepl has no ids, no ops, no interrupts, no server-side completion, no namespace tracking, no test runner integration, etc.
Editor rolls a custom protocol on top of socket REPL, or…
Editor gives up and goes to nREPL.
Pure prepl clients are nearly extinct in the wild. The one I found that qualifies is propel by Oliver Caldwell (of Conjure fame), which is delightful, about 70 lines of Clojure, and explicitly synchronous (one outstanding eval at a time). That works! But it’s not a foundation for the kind of feature set people expect from an editor.
“Real” REPL vs. tool-friendly REPL
Here’s where I land. Rich isn’t wrong that prepl is closer to a “real” REPL in the strict sense. prepl genuinely is a more faithful encoding of read-eval-print: each form goes in, each result comes out, and the semantics match what you’d get at the standard REPL prompt.
The thing is, “real REPL” is not the property you optimize for when you’re building editor tooling. The properties editor tooling actually needs are:
A way to correlate a request with its response when output and results are interleaved.
A way to multiplex – one connection, several logical conversations.
Server-side hooks for the operations every IDE expects: completion, lookup, go-to-definition, find-references, test running, stacktrace structuring, interrupt.
A protocol stable enough that ten different editors can target it without each one inventing its own dialect.
nREPL was explicitly designed for those properties. The ops, middleware, and transport abstractions exist precisely because the people building it knew the consumers are not humans typing at a prompt, they’re programs negotiating a session.
Calling nREPL “not a real REPL” is technically defensible and practically beside the point. Nobody on the consuming end is confused about what nREPL is for.
Taking stock, eight years later
I wrote about nREPL’s revival in 2018. At that point I had just finished migrating the project out of Clojure Contrib, and the goal was to give it a real home and a working development process. It was a lot of work, but in hindsight things played out pretty well.
Looking at where things ended up:
nREPL itself is healthier than it has ever been. Active maintainers, a proper manual, a steady release cadence, an actual ecosystem organization on GitHub.
Most popular Clojure editors support it. CIDER, Calva, Cursive (via its own client), Conjure, vim-iced, you name it.
babashka ships with nREPL built in. You boot a bb and you get an nREPL server, no extra dependencies. That’s how a lot of people use nREPL in scripting contexts today, and it’s been a hit.
basilisp (the Clojure dialect on Python) has nREPL support. nREPL running on Python, talking to Emacs, evaluating Clojure. Nice.
ClojureCLR has a working nREPL story now, and jank (the C++ Clojure) has nREPL on its roadmap too.
The middleware ecosystem (cider-nrepl, refactor-nrepl, piggieback, sayid, drawbridge, …) is alive, well, and continues to add features.
Meanwhile prepl is, as best as I can tell, mostly a curiosity. It got me a side project I had fun with. It did not displace nREPL.
Epilogue
The history of tooling protocols is full of cases where “purer”, “simpler”, or “more elegant” lost to “shipped, documented, and battle-tested.” LSP beat fifteen ad-hoc language protocols. DAP beat the same fifteen debuggers. nREPL beat prepl in the (Clojure) editor space.
It’s not that the simpler thing is bad. prepl is a fine, elegant little protocol, and there’s a real case for embedding it in CI scripts, ops automation, deployment pipelines, or anywhere you want to drive a Clojure VM programmatically without pulling in a server library. Use it there.
But for editor tooling? The Clojure community made an enormous, multi-year, multi-tool investment in nREPL. We have the protocol, the middleware, the manual, the books, the conference talks. nREPL works, it’s actively maintained, it’s increasingly portable across Clojure dialects, and the design decisions that Rich called out as un-REPL-like are the exact ones that make it a good substrate for editors.
So I’ll say what I felt awkward saying back in 2018: nREPL forever. It’s the right abstraction for the job, and it’s not going anywhere.
One more thing. After finishing Port I got curious what a minimal nREPL client would look like by comparison, so I went and built one. As you can imagine, it turned out to be significantly simpler. If that sounds interesting, take a look at neat, a small, language-agnostic nREPL client for Emacs.
Keep hacking!


neat: a language-agnostic nREPL client for Emacs
2026-05-20T09:00:00+03:00
I think I’ll take my REPL neat 
 My parens black and my bed at three 
 CIDER’s too sweet for me…
– Bozier
Last week I announced Port, a small prepl client for Emacs. Today I’m following it up with another small Emacs package. Meet neat, a tiny, deliberately language-agnostic nREPL client.
Why?
For years I’ve been hearing some version of the same request: “could CIDER work with my non-Clojure nREPL server?”. Babashka, Basilisp, nREPL-CLR, even some homegrown servers people built on top of nREPL for languages I’d never heard of.¹ The answer was always the same kind of squishy “sort of, in theory, with caveats”, because while bare nREPL is genuinely language-agnostic, CIDER is not. CIDER was built for Clojure and assumes Clojure pretty much everywhere.
I always thought the right answer was “let’s gradually make CIDER more language-agnostic.” That’s the kind of plan that sounds reasonable until you actually try it.
The thing that pushed me over the edge was, oddly enough, building Port. Port is small, focused, and doesn’t try to be CIDER. Working on it for a couple of weeks reminded me how (deceptively) productive it is to start from a clean slate when the new requirements don’t match the assumptions baked into a mature codebase. Trying to retrofit CIDER into a language-agnostic shape would have meant fighting with every helper that ever assumed clojure.repl exists, every middleware contract cider-nrepl defines, every project-type heuristic that knows about deps.edn and project.clj and nothing else. A whole lot of “is the server Clojure, or is it the other thing?” branches. The Port experience reaffirmed that the right move for a genuinely different client is a new project, not a thousand cuts to an existing one.
So neat was born. The name is short, says what it does (it’s neat, both in the small-and-tidy sense and in the “no deps, no special assumptions, just the protocol” sense), and conveniently leaves room for puns I haven’t fully committed to yet. I might land on a backronym one day. For now it’s just “neat”.
What neat actually is
neat is a small Emacs nREPL client. The code is split across four files:
neat-bencode.el: bencode encode/decode.
neat-client.el: TCP connections, request dispatch, the standard nREPL ops.
neat-repl.el: a comint-derived REPL buffer.
neat.el: the entry point, customization group, and neat-mode minor mode for source buffers.
It only uses Emacs builtins. There are no external runtime dependencies, not even on clojure-mode, because neat doesn’t assume Clojure on the other end. If you write clojure-mode, fennel-mode, hy-mode, or anything else that talks nREPL, you turn on neat-mode in that buffer and it just works.
The connection routing is also intentionally library-friendly. There’s a buffer-local neat-current-connection override so downstream packages can implement their own routing logic, plus a global default for the simple “one server at a time” case that most people will want.
Capability discovery is done at connect time via the nREPL describe op. neat doesn’t hardcode “this server has completions, this one doesn’t” assumptions. If the server reports a completions op, the CAPF backend lights up (with type annotations next to each candidate, when the server provides them). If it reports lookup, eldoc starts working and M-. jumps to definitions via an xref backend. If neither is there, you still get a perfectly serviceable raw REPL.
Basic usage
Start an nREPL server. Anything that speaks the protocol will do. For a Clojure server:
class="highlight">1
2
3
4
5
clj -M:nrepl
# or
bb nrepl-server :port 7888
# or
lein repl :headless :port 7888
Then in Emacs:
class="highlight">1
M-x neat RET localhost RET 7888 RET
A REPL buffer pops up, the prompt follows the server’s reported namespace, and you can type expressions at it. Multi-line input works because RET only submits when the form parses as balanced under neat-repl-input-syntax-table (Emacs Lisp syntax by default, which is close enough for any Lisp). Input history is persisted across sessions.
If there’s a .nrepl-port file in the project, the prompt defaults to its contents, so M-x neat RET RET is enough to connect.
To evaluate from a source buffer, turn on the minor mode:
class="highlight">1
M-x neat-mode
The familiar bindings are there, intentionally compatible with what CIDER users expect:
Key Command
C-c C-e neat-eval-last-sexp
C-c C-c neat-eval-defun
C-c C-r neat-eval-region
C-c C-b neat-eval-buffer
C-c C-l neat-load-buffer-file
C-c C-z neat-switch-to-repl
C-c C-k neat-interrupt-eval
C-c M-n neat-set-ns
C-c C-d C-d neat-show-doc-at-point
M-. xref-find-definitions
M-, xref-go-back
neat-eval-buffer ships the buffer contents as an eval op; neat-load-buffer-file uses the standard load-file op instead, so the server can attribute file and line numbers to errors. Use the latter when you’re actually loading a file from disk and care about good diagnostics.
neat-set-ns sets the buffer-local neat-ns, which gets sent as the ns field on every eval op from that buffer. For languages where the namespace is declared in the source (Clojure’s (ns foo.bar), etc.), swap in a parser via neat-buffer-ns-function.
For juggling multiple connections, M-x neat-list-connections opens a tabulated-list buffer with one row per live connection, where you can set the default or disconnect interactively.
That’s roughly the whole user-facing surface today. There’s no jack-in command, no inspector, no debugger, no test runner. Likely there will never be, but if you need those you should probably be using CIDER anyways…
Should you use it?
If you write Clojure and CIDER works for you, keep using CIDER. It’s mature, full-featured, and supported, and I’m going to keep working on it for as long as people use it. Nothing about neat changes that.
But if you find yourself in one of these situations:
you write a non-Clojure language whose runtime ships an nREPL server, and you’ve been muddling through with a half-supported CIDER setup,
you write Clojure but you value minimalism and don’t need the full CIDER feature set,
you’re building an Emacs package that needs to talk nREPL and you want a small, dependency-free library to build on,²
then neat might be a better fit. It’s small enough that you can read the whole thing in an afternoon, and the library/UI split (neat-bencode and neat-client are perfectly usable from other packages) is genuinely designed for downstream consumers.
The bigger picture
neat is part of a broader push I’ve been chewing on for a while now: making nREPL a healthy multi-language ecosystem rather than a Clojure-only protocol. That push has three legs:
An actual nREPL specification. The spec.nrepl.org draft is (will be) the formal version of what today is “whatever nREPL the project does”.
Reference clients. neat is one. The point of building a deliberately Clojure-free client is that it stress-tests the spec. Anywhere neat ends up needing to special-case the server, the spec has a gap.
A compatibility test suite. The parameterised integration suite in neat already runs the same assertions against multiple servers and surfaces real divergences (Clojure batching (println "hi") into a single out message where Basilisp emits two, for example). I’d like to grow this into a portable suite that any nREPL server can self-check against.
This is also why I keep teasing a “reference CLI client” in conversations. An editor client is one thing, but a small command-line nREPL client written in a non-Lisp language would be a much sharper test of how language-agnostic the protocol really is. neat is plausibly a precursor to that. Time will tell how far I push this; for now I just wanted to get the Emacs side moving.
Thanks
As always, big thanks to Clojurists Together and everyone supporting my open source work. You make it possible for me to keep tweaking and improving CIDER, nREPL, clj-refactor, and friends, and occasionally try something “neat” on the side. neat isn’t replacing any of the existing Clojure tooling for Emacs. It’s just another tool in the box for the people who want it.
Feedback, ideas, and contributions are most welcome over at the issue tracker.
Keep hacking!
https://github.com/clojure-emacs/cider/issues/3905 ↩︎
For a long time I planned to extract CIDER’s nREPL client code into a reusable package, but now that we have neat I probably will finally abandon this idea. ↩︎


Port: a minimalist prepl client for Emacs
2026-05-12T09:00:00+03:00
For ages I’ve had “add prepl support to CIDER” sitting somewhere in the back of my head. CIDER is built firmly around nREPL, but prepl ships with Clojure itself, and the appeal of dropping the external REPL server requirement is obvious. Recently, as part of a broader internals cleanup “mini-project” in CIDER, I finally sat down and put a prototype together: cider#3899.
The good news is that the prototype sort of worked. The bad news is that the more I poked at it, the more I kept running into the same pattern. CIDER assumes ops, sessions, request ids, and a whole structured protocol that prepl simply doesn’t have. The amount of CIDER code that would need to grow “is this nREPL or prepl?” branches added up quickly, and I’d be papering over prepl’s limitations in dozens of subtle places. The exercise was fun, but it ended up reaffirming my long-standing belief that nREPL is a much better fit for editor tooling than prepl is.
The exercise did leave me thinking though. What if, instead of bolting prepl onto CIDER, I built a small standalone client in the spirit of inf-clojure and monroe? Something tiny and focused that doesn’t have to pretend to be CIDER, and where prepl’s quirks would be the design rather than something to work around.
Conveniently, I was on vacation in Portugal at the time, where I spent a few days in Porto, and the name pretty much picked itself. Port was born. It kept us firmly in the land of fun, drink-inspired Clojure-on-editor names: CIDER, Calva (after Calvados, the apple brandy), and now Port (the famous fortified wine). The protocol Port talks to is prepl, over a TCP port, so the pun was hard to pass up.
This time around I didn’t manage to land on a backronym I love (at least not yet). The contenders so far:
prepl omnipotent repl toolkit (my favorite so far)
prepl-operated repl toolkit
peak optimized repl toolkit
Naming is hard. I remain open to better suggestions. :D
Scope, or what Port isn’t
Port is a side project. I don’t plan to invest serious time in it past the point I consider it feature-complete, which won’t be far beyond what’s already there. The deliberate goal is to keep it simple and focused, and its feature set will stay close to inf-clojure and monroe. Port is not competing with CIDER. If you want the full feature set (debugger, inspector, test runner, profiler, structured stacktraces, refactor support), CIDER + cider-nrepl is, and will remain, the way.
What Port gives you today is a small, dependable Clojure REPL that you can hook into Emacs without any external dependencies, just a stock Clojure JVM with a prepl listening on a port.
A few architectural notes
If you’re up for the long version, doc/design.md goes deep. Here’s the short version of what prepl gives you compared to nREPL:
No bencode. prepl emits EDN-tagged maps, one per line. This might be a feature or a problem, depending on your perspective.
No middleware. Whatever the server prints is what you get. No interception, no extension surface.
No sessions. There’s one thread per TCP connection.
No ops. You send a Clojure form, the server evaluates it, and prints back tagged messages: :ret, :out, :err, :tap, plus an :exception true flag on errors.
No request id. This is the main issue. Tags identify the kind of message, not which request produced it.
That last point is the central design constraint. If you want to issue a request and reliably read back its result without accidentally consuming output from an unrelated background future or tap>, you need to layer correlation on top of the protocol. Port does this with two tricks:
Two sockets per session. A user socket drives the REPL buffer with raw streaming output, and a separate tool socket carries helper-command requests. Background prints from future/agent on the user thread don’t bleed into the tool channel.
A bootstrap form. On connect, the tool socket evaluates a one-shot form that defines a port.tooling/-eval wrapper. Every subsequent helper call goes through it, which captures *out* / *err* and returns a tagged map containing the request id. The client matches the id against a pending-callback registry.
This is what nREPL provides via sessions and ops, just reinvented at the TCP layer. It’s a fair amount of work for something nREPL gives you for free, which only strengthens my view that nREPL is the better protocol for editor tooling. Still, it was an interesting and educational exercise.
Zero dependencies
One thing I’m fairly proud of: Port has no hard dependencies. You’ll want either clojure-mode or clojure-ts-mode installed for the source-buffer side of things, but Port itself only soft-depends on them via runtime fboundp checks. Hook it onto whichever one(s) you actually use. I intend to keep it that way. Dependency creep is a real problem in the Emacs (every?) ecosystem, and a small package should stay small.
What’s there in 0.1
I tagged v0.1.0 yesterday. It’s small but already perfectly usable:
M-x port “jacks in” (bootstraps) (auto-detects deps.edn / project.clj / bb.edn, starts a server and connects to it)
single-buffer REPL with persistent input history, completion, and eldoc at the prompt
interactive evaluation from source buffers with pretty-printed results
structured stacktrace buffer with cause chain and navigable frames
M-. find-definition that follows into jar sources
doc/source/apropos/macroexpand helpers
MELPA submission is queued up next. After that, expect Port to be in burst-driven maintenance mode like most of my smaller projects.
Feedback, ideas, and contributions are most welcome. The issue tracker is the right place.
Closing thoughts
Funny thing, I’d never actually written any code against prepl until I started this project. It was fun to spend some quality time with the “competition” of my beloved nREPL. Working with a different protocol always teaches you something about the one you’re used to, and I came away from this with a renewed appreciation for both: prepl is genuinely elegant for what it is, and nREPL is genuinely well-designed for what we use it for.
Big thanks to Clojurists Together and everyone else who supports my OSS Clojure work. You rock! Now if you’ll excuse me, I have new releases of CIDER, clj-refactor, and refactor-nrepl to get back to.
Keep hacking!
(think)

Neocaml 0.9: A Better REPL, Dune/Opam Completion, and More Robustness

A much nicer REPL experience

Completion for Opam and Dune, no LSP required

Robustness improvements

OCaml 5.5 support, and the ABI 14 balancing act

Roadmap and docs

Give it a Try

Emacs loves AsciiDoc

Background

Less is more, unless it’s modes

Recent developments

Give it a try

nREPL Forever

Sky is the limit

Reality Check

“Real” REPL vs. tool-friendly REPL

Taking stock, eight years later

Epilogue

neat: a language-agnostic nREPL client for Emacs

Why?

What neat actually is

Basic usage

Should you use it?

The bigger picture

Thanks

Port: a minimalist prepl client for Emacs

Scope, or what Port isn’t

A few architectural notes

Zero dependencies

What’s there in 0.1

Closing thoughts
