Necessary Pigeonholing Mechanism
Wondering what’s next for npm?Check out our public roadmap! »


0.3.0-beta • Public • Published


Unravel your REPL

npm version

Unravel is a simple command-line client for Clojure REPLs. It is based on the unrepl protocol, so instead of relying on nREPL, unravel communicates with your Clojure process through a Socket Server REPL.

Unravel provides a richer user experience by:

  • showing docstring and arglist of vars as you type them
  • eliding long or infinite sequences but allowing the user to request a continuation


To use unravel you need Clojure 1.8.0 or above.

Simple installation using npm

On Linux or macOS you can install (or update) unravel via npm:

sudo npm install -g unravel-repl

This installs the unravel binary and adds it to your PATH.

On macOS you can also use

brew install bfontaine/utils/unravel

Installation from git

For a more up-to-date version, you can check out master:

git clone
cd unravel
npm install
scripts/run [--debug] <host> <port>


Connect to a Clojure Socket REPL:

unravel [--debug] <host> <port>

In addition to common readline shortcuts, the following keybindings are available:

  • Control-D: exit the REPL
  • Control-O: show docstring for symbol under the cursor
  • <Tab>: complete var or namespace

Lines starting with #__ are treated as special commands and interpreted by the REPL client. The following specials are available:

  • #__help shows a help screen
  • #__1, #__2, #__3 ...: expand the numberd lazy seq ellipsis
  • #__: expand the most recent lazy seq ellipsis

Launching a Socket REPL

You can easily enable the Socket REPL feature for your Clojure project, whether you use boot, lein or a plain clojure jar. The Socket REPL does not have any dependencies other than Clojure 1.8.0.

To launch a Clojure process with a Socket REPL listening on port 50505 using boot, use:

boot -i "(do (require 'clojure.core.server) (clojure.core.server/start-server {:port 50505 :name :repl :accept 'clojure.core.server/repl}))" wait

Or if you have boot >= 2.7.2:

boot socket-server --port 50505 wait

Using Leiningen:

JVM_OPTS='-Dclojure.server.myrepl={:port,50505,:accept,clojure.core.server/repl}' lein repl

Using a plain Clojure jar:

java -Dclojure.server.myrepl="{:port 50505,:accept,clojure.core.server/repl}" -jar ~/.m2/repository/org/clojure/clojure/1.8.0/clojure-1.8.0.jar

You can then connect to the process by running unravel in a separate terminal window:

unravel localhost 50505



  • Print vars correctly
  • Update unrepl
  • Use 'user as init-ns
  • Don't write to socket after closing connection
  • Update to Lumo 1.6.0


  • Enable lumo caching (3x startup time improvement)
  • Interrupt running process on SIGINT
  • Fix exceptions when connected to Boot-based socket server


  • Live docs for vars and namespaces
  • Use separate tooling connection for tab completion and docs
  • Start in "user" namespace


  • Fix installation via NPM


  • Add repl specials
  • Expand lazy seq ellipsis
  • Fix issue with non-existant namespaces


  • Tab completion (namespaces and vars)
  • Pretty-print exceptions
  • Use tagged literals
  • Re-prompt on newline or Control-C


Persistent history


Distribute via npm


Show docstring

Future work

See for a list of planned improvements. Unravel is developed in conjunction with unrepl.


  • The Ultimate Guide To Clojure REPLs on the Socket REPL

  • replicant: proof of concept of using Socket REPL for tooling

Join the #unrepl channel in the Clojurians slack!


See [].


(c) 2017 Paulus Esterhazy

Unrepl payload.clj (c) 2017 Christophe Grand

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.


npm i unravel-repl

DownloadsWeekly Downloads






Last publish


  • avatar