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