clojure-repl-eval

name	clojure-repl-eval
description	Evaluate Clojure code via nREPL using clj-nrepl-eval. Use this when you need to test code, check if edited files compile, verify function behavior, or interact with a running REPL session.

Clojure REPL Evaluation

When to Use This Skill

Use this skill when you need to:

• Verify that edited Clojure files compile and load correctly
• Test function behavior interactively
• Check the current state of the REPL
• Debug code by evaluating expressions
• Require or load namespaces for testing
• Validate that code changes work before committing

How It Works

The clj-nrepl-eval command evaluates Clojure code against an nREPL server. Session state persists between evaluations, so you can require a namespace in one evaluation and use it in subsequent calls. Each host:port combination maintains its own session file.

Instructions

0. Discover and select nREPL server

First, discover what nREPL servers are running in the current directory:

clj-nrepl-eval --discover-ports

This will show all nREPL servers (Clojure, Babashka, shadow-cljs, etc.) running in the current project directory.

Then use the AskUserQuestion tool:

• If ports are discovered: Prompt user to select which nREPL port to use:

  • question: "Which nREPL port would you like to use?"
  • header: "nREPL Port"
  • options: Present each discovered port as an option with:
    • label: The port number
    • description: The server type and status (e.g., "Clojure nREPL server in current directory")
  • Include up to 4 discovered ports as options
  • The user can select "Other" to enter a custom port number

• If no ports are discovered: Prompt user how to start an nREPL server:

  • question: "No nREPL servers found. How would you like to start one?"
  • header: "Start nREPL"
  • options:
    • label: "deps.edn alias", description: "Find and use an nREPL alias in deps.edn"
    • label: "Leiningen", description: "Start nREPL using 'lein repl'"
  • The user can select "Other" for alternative methods or if they already have a server running on a specific port

IMPORTANT: IF you start a REPL do not supply a port let the nREPL start and return the port that it was started on.

1. Evaluate Clojure Code

Evaluation automatically connects to the given port

Use the -p flag to specify the port and pass your Clojure code.

Recommended: Use heredoc via stdin to avoid shell escaping issues. The single-quoted delimiter (<<'EOF') passes all characters through literally.

clj-nrepl-eval -p <PORT> <<'EOF'
(+ 1 2 3)
EOF

For multiple expressions:

clj-nrepl-eval -p <PORT> <<'EOF'
(def x 10)
(+ x 20)
EOF

2. Display nREPL Sessions

Discover all nREPL servers in current directory:

clj-nrepl-eval --discover-ports

Shows all running nREPL servers in the current project directory, including their type (clj/bb/basilisp) and whether they match the current working directory.

Check previously connected sessions:

clj-nrepl-eval --connected-ports

Shows only connections you have made before (appears after first evaluation on a port).

3. Common Patterns

Require a namespace (always use :reload to pick up changes):

clj-nrepl-eval -p <PORT> "(require '[my.namespace :as ns] :reload)"

Test a function after requiring:

clj-nrepl-eval -p <PORT> "(ns/my-function arg1 arg2)"

Check if a file compiles:

clj-nrepl-eval -p <PORT> "(require 'my.namespace :reload)"

Multiple expressions:

clj-nrepl-eval -p <PORT> "(def x 10) (* x 2) (+ x 5)"

Complex multiline code:

clj-nrepl-eval -p <PORT> <<'EOF'
(def x 10)
(* x 2)
(+ x 5)
EOF

With custom timeout (in milliseconds):

clj-nrepl-eval -p <PORT> --timeout 5000 "(long-running-fn)"

Reset the session (clears all state):

clj-nrepl-eval -p <PORT> --reset-session
clj-nrepl-eval -p <PORT> --reset-session "(def x 1)"

Available Options

• -p, --port PORT - nREPL port (required)
• -H, --host HOST - nREPL host (default: 127.0.0.1)
• -t, --timeout MILLISECONDS - Timeout (default: 120000 = 2 minutes)
• -r, --reset-session - Reset the persistent nREPL session
• -c, --connected-ports - List previously connected nREPL sessions
• -d, --discover-ports - Discover nREPL servers in current directory
• -h, --help - Show help message

Important Notes

• Prefer heredoc via stdin: Use clj-nrepl-eval -p <PORT> <<'EOF' ... EOF to avoid shell escaping issues
• Sessions persist: State (vars, namespaces, loaded libraries) persists across invocations until the nREPL server restarts. --reset-session only resets the nREPL session (clearing dynamic vars like *e, *1), not def'd vars or loaded namespaces
• Automatic delimiter repair: The tool automatically repairs missing or mismatched parentheses
• Always use :reload: When requiring namespaces, use :reload to pick up recent changes
• Default timeout: 2 minutes (120000ms) - increase for long-running operations
• Input precedence: Command-line arguments take precedence over stdin

Typical Workflow

1. Discover nREPL servers: clj-nrepl-eval --discover-ports
2. Use AskUserQuestion tool to prompt user to select a port
3. Require namespace:

   clj-nrepl-eval -p <PORT> "(require '[my.ns :as ns] :reload)"
   

4. Test function:

   clj-nrepl-eval -p <PORT> "(ns/my-fn ...)"
   

5. Iterate: Make changes, re-require with :reload, test again

Examples

Discovery

clj-nrepl-eval --connected-ports

Heredoc for Multiline Code

clj-nrepl-eval -p 7888 <<'EOF'
(defn greet [name]
  (str "Hello, " name "!"))

(greet "Claude")
EOF

Heredoc Simplifies String Escaping

Heredoc avoids shell escaping issues with quotes, backslashes, and special characters:

# With heredoc - no escaping needed
clj-nrepl-eval -p 7888 <<'EOF'
(def regex #"\d{3}-\d{4}")
(def message "She said \"Hello!\" and waved")
(def path "C:\\Users\\name\\file.txt")
(println message)
EOF

# Without heredoc - requires complex escaping
clj-nrepl-eval -p 7888 "(def message \"She said \\\"Hello!\\\" and waved\")"

Working with Project Namespaces

# Test a function after requiring
clj-nrepl-eval -p 7888 <<'EOF'
(require '[clojure-mcp-light.delimiter-repair :as dr] :reload)
(dr/delimiter-error? "(defn foo [x]")
EOF

Verify Compilation After Edit

# If this returns nil, the file compiled successfully
clj-nrepl-eval -p 7888 "(require 'clojure-mcp-light.hook :reload)"

Session Management

# Reset session if state becomes corrupted
clj-nrepl-eval -p 7888 --reset-session

Load, Test, Iterate

# After editing a file, reload and test in one command
clj-nrepl-eval -p 7888 <<'EOF'
(require '[my.namespace :as ns] :reload)
(ns/my-function test-data)
EOF

Run Tests After Changes

clj-nrepl-eval -p 7888 <<'EOF'
(require '[my.project.core :as core] :reload)
(require '[my.project.core-test :as test] :reload)
(clojure.test/run-tests 'my.project.core-test)
EOF