Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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

On macOS, the easiest way to install unravel is via brew:

brew install unrepl/bin/unravel

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

sudo npm install -g unravel-repl

In either case you should end up with an unravel binary in your PATH:

unravel --version

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

As of Clojure 1.9 you can use the clojure command line tool:

clojure -J-Dclojure.server.myrepl="{:port 50505,:accept,clojure.core.server/repl}"

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.