Skip to content

The Calva REPL UI#

When you connect Calva to a REPL, you gain access to a complete interactive development environment. The REPL UI consists of several components that work together to provide a seamless evaluation and feedback experience.

Managing Multiple Connections#

Definitions:

  • REPL Connection: An active nREPL connection to a running Clojure/ClojureScript environment. Each connection is associated with a project root and a host/port.
  • REPL Session: A logical session within a REPL connection. Connections have at least one session and at most two. Sessions are associated with a project root (via the connection) and file patterns (partial globs), these associations help the automatic evaluation routing: file → session.

Calva keeps every nREPL connection alive until you explicitly disconnect it. This makes it possible to work with several apps (or the same app in multiple environments) at once from the same VS Code window. By default Calva will automatically route evaluations to a session based on file path and file type.

  • The REPL Sessions menu lists every registered session name, indicating which one is being targeted by the auto-router for the currently active file. You can bypass the auto-routing by pinning one of the sessions.
  • The command palette entry Calva: Disconnect from the REPL (also available from the REPL menu) opens a menu that shows all active connections, with their sessions names, host/port, and project root. Pick a single connection to disconnect only that REPL or choose Close all REPL connections.
  • Sessions names are defined by the connect sequence used for connecting a REPL. Calva has built-in sequences for several Clojure dialects/runtimes, defining default session names. The session names are customizable via custom connect sequences.
  • When two or more sessions use the same session name, numbered suffixes will be used to separate the sessions.

E.g. connect three Babashka repls and you will have one session named bb another named bb:2, and a third named bb:3. If you then connect two Clojure + ClojureScript repls using default session names, you will have four more sessions named: clj, cljs, clj:4, cljs:4.

REPL Sessions Menu

UI Components Overview#

File Editors#

Every Clojure/ClojureScript file you have open becomes a REPL-connected environment. You can evaluate code directly in your editor and see results displayed inline. The first line of evaluation results appears as an inline decoration, while complete output goes to your configured output destination.

Output Destinations#

Calva provides several output destinations where evaluation results, stdout/stderr, and other REPL messages can be displayed. Each destination has different capabilities suited for different use cases. See Output Overview for details on all available destinations, their feature comparison, and how to configure which output goes where.

REPL Window#

The REPL Window is a special Clojure file that provides an interactive prompt for experimental code. It automatically tracks the namespace of whatever file you're evaluating code in, making it easy to explore your code interactively. The window supports full Paredit, history recall, and can be used with the debugger.

Inspector#

The Inspector is a tree view that lets you explore evaluation results as expandable data structures. All REPL evaluation results are automatically added to the inspector, allowing you to drill down into nested collections and examine your data in detail.

Command Palette#

All REPL commands are available through VS Code's Command Palette (Ctrl+Shift+P / Cmd+Shift+P). Here are the most essential commands for interactive development:

  • Load/Evaluate Current File: Ctrl+Alt+C Enter - Load the current file and its dependencies
  • Evaluate Current Form: Ctrl+Enter - Evaluate the form at cursor and show result inline
  • Evaluate Top-Level Form: Alt+Enter - Evaluate the enclosing top-level form (works inside comment blocks)
  • Show REPL Window: Ctrl+Alt+O R - Open and focus the REPL Window
  • Send Form to REPL Window: Ctrl+Alt+C Ctrl+Alt+E - Copy current form to REPL Window
  • Run Namespace Tests: Ctrl+Alt+C T - Run all tests in the current namespace
  • Run Current Test: Ctrl+Alt+C Ctrl+Alt+T - Run the test at cursor
  • Toggle Pretty Printing: Ctrl+Alt+C P - Enable/disable pretty printing (also available via status bar)
  • Interrupt Running Evaluation: Available in REPL status bar menu when connected
  • Show Output Destination: Ctrl+Alt+O O - Open the configured output destination
  • Disconnect from the REPL: Opens a quick pick listing every active connection so you can disconnect from a single connection or select Close all REPL connections when you need a fresh slate

Search the command palette for Calva evaluate to find some more commands related to code evaluation at the REPL.

The Status Bar#

The status bar displays REPL connection status and provides quick access to common REPL operations.

Connection Status#

The "REPL" connection indicator shows the current state of your REPL connection:

Status Bar REPL Connected

States:

  • Disconnected - REPL $(zap) (gray) - Click to open the REPL menu and start Jack-in or Connect
  • Launching - Launching REPL using <method> (white) - Click to interrupt the launch process
  • Connecting - REPL - trying to connect - Click to interrupt the connection attempt
  • Connected - REPL $(zap) (ember) - Click to open the REPL menu with commands for managing your connection. Calva keeps existing connections alive when you start another REPL

When connected, the tooltip displays the connection details: nrepl://hostname:port

REPL Status Colors#

You can customize the REPL indicator colors for different connection states using these settings:

For dark themes: * calva.statusColor.dark.connectedStatusColor - Color when connected (default: green) * calva.statusColor.dark.disconnectedColor - Color when disconnected (default: gray) * calva.statusColor.dark.launchingColor - Color during launch (default: orange) * calva.statusColor.dark.typeStatusColor - Color for session type indicator

For light themes: * calva.statusColor.light.connectedStatusColor * calva.statusColor.light.disconnectedColor * calva.statusColor.light.launchingColor * calva.statusColor.light.typeStatusColor

Session Type Status#

Once connected, the session type indicator shows which REPL you're currently working with:

Status Bar REPL Connected, session

For .cljc files (Clojure Common files that can run on both CLJ and CLJS), the indicator shows .cljc → clj or .cljc → cljs depending on which session is active for that file.

The indicator is always clickable when the REPL is connected. Clicking it opens the REPL Sessions menu, which provides:

  • A list of connected sessions – select one to pin it (the indicator will show $(pin) while pinned). When auto-routing is active, the currently selected session is marked with $(check) so you can see which REPL is in use at a glance. Sessions in pairs show a cljc indicator for the session that handles .cljc files, and non-target sessions have a button to become the cljc target.
  • Auto-route – return to Calva's default routing based on connect sequence globs.
  • Select session for REPL window – (Only shown when the REPL window is focused) Override which session the REPL window uses for evaluations.

The cljc routing preference is per-connection. When you have multiple REPL connections, each connection remembers its own cljc target session independently. If you pin a session, that pin takes precedence for all files until you return to auto-route.

These options make it easy to temporarily lock the routing, quickly inspect available sessions, or manage .cljc file routing per connection. See The REPL Window for more details.

REPL Window Session Command#

The command Calva: Select REPL Window Session is also available from the command palette. It can be invoked programmatically with a session key argument to bypass the picker:

// Via VS Code API
vscode.commands.executeCommand('calva.selectReplWindowSession', 'cljs');

// Or without argument to show the picker
vscode.commands.executeCommand('calva.selectReplWindowSession');

This is useful for keyboard shortcuts or automation scripts that need to quickly switch the REPL window's session.

CLJS Build Selector#

When connected to a ClojureScript REPL that supports builds (Figwheel or shadow-cljs), this indicator shows the currently connected build:

  • Build connected - Shows the build name (e.g., :app)
  • No build - Shows No build connected

Click the indicator to switch to a different build or connect to a build if none is selected.

Shadow-CLJS Runtime Selector#

When using shadow-cljs, this indicator shows the currently selected runtime:

  • Runtime selected - Shows rt: <runtime-id> (e.g., rt: 3)
  • No runtime - Shows No Runtime

Click the indicator to open the runtime selection menu. The tooltip displays additional details like the runtime description and how long it has been connected. See shadow-cljs for more about runtime selection.

See also: shadow-cljs.

Pretty Print Toggle#

The pprint indicator shows whether pretty printing is enabled for evaluation results:

  • Enabled (default) - Shows in normal color, click to turn off
  • Disabled - Shows in gray, click to turn on

Pretty printing formats evaluation results for better readability. See Pretty Printing for detailed configuration options including maxLength, maxDepth, and print engine selection.

See Also#