Documentation for REPLSmuggler.

REPLSmuggler is meant to evaluate code coming from various clients in your REPL. The main goal is for an editor to send a bunch of lines of code with some metadata giving the name of the file and the line. REPLSmuggler will evaluate the code and send back the return value. If an error is raised, it will send the traceback to the client.

See also the the companion plugin for NeoVim.


Using REPLSmuggler is as simple as:

julia> using REPLSmugglers
julia> smuggle()
[ Info: Ahoy, now smuggling from socket /run/user/1000/julia/replsmuggler/contraband_clandestine_operation.
Task (runnable) @0x0000753a784c6bd0

You are then able to send code and get notified when an error happens.

smuggle can also be used the other way around, to directly send diagnostics to your editor. For example, if your editor has smuggled the following function:

function bad_bad_bad()

You can send back diagnostics to the editor directly from the REPL by catching an exception.

julia> try
catch exc

You can even send directly diagnostics, without looking for code that has actually been sent by the editor:

julia> smuggle("hey", "foo", "$(pwd())/test.jl", 11, "none")

There's also an extension to work with JET's reports. Say you smuggled the following functions:

function foo(s0)
  a = []
  for s in split(s0)
    push!(a, bar(s))
  return sum(a)
bar(s::String) = parse(Int, s)

You can smuggle back to the editor JET's report as follow:

julia> smuggle(@report_call foo("1 2 3"))




Return a path where REPLSmuggler can store its socket, depending on the OS.

  • For Linux: /run/user/<uid>/julia/replsmuggler/
  • For Windows: \\.\pipe\
  • For MacOS: ~/Library/Application Support/julia/replsmuggler/
smuggle(title, diagnostic, filename, line, function)

Smuggle a diagnostic in file filename, function function, at line line.


The notification will be sent to all connected sessions.

smuggle([name]; basepath=basepath(), serializer=MsgPack)

Start a server using a UNIX sockets with a random name and MsgPack.jl as a serializer. The socket will be stored in joinpath(basepath, name). If name is not provided, REPLSmuggler will try randomly generated names until a non-already-existing socket name is found.

For example, on linux, you could find the socket in /run/user/1000/julia/replsmuggler/clandestine_underworld if the name was chosen to be clandestine_underworld.

The socket name is displayed in the REPL, and the server is accessible through CURRENT_SMUGGLER.

See also basepath.

smuggle(exception, stackframes=stacktrace(Base.catch_stacktrace()))

Smuggle an exception. Can be used to report on exceptions thrown by code evaluated by the user in the REPL.


The notification will be sent to all connected sessions.


catch exc



Smuggle REPLSmuggler's history within REPL's history. This is probably fragile, as the code is based on undocumented REPL.jl code.




Definition of the protocol used by REPLSmuggler.jl. It is based on MsgPack-RPC, see here:


The actual (de)serialization from and to MsgPack objects is handled by MsgPack.jl through a lightweight wrapper defined in MsgPackSerializer.

The protocol consists of requests messages and their corresponding response messages. There can also be notification messages.

As per the specification, a request is serialized to an array of four elements, that could be written in Julia as follow:

[type::UInt8, msgid::UInt32, method::String, params::Vector{Any}]

Where type = 0x00. For convenience, we define a structure and teach MsgPack.jl to serialize it.

A response message should be serialized as:

[type::UInt8, msgid::UInt32, error::Any, result::Any]

Where type = 0x01. msgid is the identifier of the corresponding request.

Finally, a notification has the form:

[type::UInt8, method::String, params::Vector{Any}]

Where type = 0x02.

Defined methods for requests.

We allow the client to run the following methods. If a method is unknown by the server, it will raise an error.

  • eval: Evaluate a chunk of code. Parameters:
    • file::String
    • line::UInt32
    • code::String
  • interrupt: Interrupt the current evaluation. No parameter.
  • exit: Stop the current session. No parameter.

Responses of the server.

The result field is a string of what would be printed in the REPL. It is empty if an error occured.

If an error occured, then the error field is a three-elements array structured as follow:

  • exception::String: Name of the exception, e.g. "ValueError",
  • exception_text::String: Text, e.g. "This value cannot be < 0.",
  • stacktrace::Vector{Tuple{String, UInt32, String}}: The stacktrace, with each row being (file, line, function).

Notifications by the server.

Currently, the following notifications can be sent by the server. If a notification received by the client is unknown, it should simply be ignored without erroring.

  • handshake: Sent at the begining of a session, mainly to ensure the correct version of the protocol is being used. Parameters:
    • myname::String: Name of the server. Will typically be REPLSmuggler, but could be replaced if other implementations of the protocol were to exist.
    • version::String: A sementic versioning version number telling the client which version of the protocol is being used by the server.
  • diagnostic: Sent following the evaluation of some code by the user from the REPL. For example, this could be used via a direct call to display a diagnostic on a specific line, or to report an exception from some code evaluated by the user, or report diagnostic from other packages such as JET.jl. This is very similar to how an exception would be handled when executing code. Parameters:
    • title::String: Short title for the diagnostic.
    • diagnostic::String: The diagnostic that is to be displayed.
    • stacktrace::Vector{Tuple{String, UInt32, String}}: The stacktrace, with
    each row being (file, line, function).

Typical session:

  • The client connects to the server.
  • The server sends a handshake notification.
  • The client checks it is running the correct version of the protocol.
  • The client runs requests (eval, interrupts...)
  • The server responds to the requests.
  • The client runs exit.
  • The server stops all the running code and close the session.

Note that any interrupt of the connection (i.e. closing the socket) is equivalent to sending an exit request.

dispatchonmessage(protocol, f, args...; kwargs)

Deserialize a request, and send it to the correct method of f. f should define methods with a first parameter being of type Val{:method} where method can be: "eval", "interrupt", or "exit". f is called as:

f(Val(method), args..., request.msgid, request.params...; kwargs...)

A ProtocolException might be raised if the request is malformed.




Implementation of the server for REPLSmuggler.jl -the brain of REPSmuggler.jl.

The handling of the communication protocol is done by Protocols.

The implementation is heavily inspired by the server from RemoteREPL.jl.

evaluate_entry(session, msgid, file, line, value)

Evaluate the code in value in the context of the given session, replacing the context of the code with file and line. If an error occurs, it will put a using Base: JuliaSyntax Protocols.Error to the outgoing channel of the session.


Default implementation