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 available nREPL servers

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

clj-nrepl-eval --discover-ports

This will show all nREPL servers (Clojure, Babashka, etc.) running in the current project directory. If no servers are found, ask the user if they would like you to start one.

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 by default (provides cleaner, more readable output):

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

For multiline code:

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

Alternative: As a command-line argument:

clj-nrepl-eval --port 7888 "(+ 1 2 3)"

Alternative: Via stdin pipe:

echo "(+ 1 2 3)" | clj-nrepl-eval -p 7888

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 7888 <<'EOF'
(require '[my.namespace :as ns] :reload)
EOF

Test a function after requiring:

clj-nrepl-eval -p 7888 <<'EOF'
(ns/my-function arg1 arg2)
EOF

Check if a file compiles:

clj-nrepl-eval -p 7888 <<'EOF'
(require 'my.namespace :reload)
EOF

Multiple expressions:

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

With custom timeout (in milliseconds):

clj-nrepl-eval -p 7888 --timeout 5000 <<'EOF'
(long-running-fn)
EOF

Reset the session (clears all state):

clj-nrepl-eval -p 7888 --reset-session
clj-nrepl-eval -p 7888 --reset-session <<'EOF'
(def x 1)
EOF

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 format: Use heredoc (<<'EOF' ... EOF) by default for cleaner, more readable output - even for single-line expressions
• Sessions persist: State (vars, namespaces, loaded libraries) persists across invocations until the nREPL server restarts or --reset-session is used
• 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. Choose a port from the discovered servers
3. Require namespace:

   clj-nrepl-eval -p 7888 <<'EOF'
   (require '[my.ns :as ns] :reload)
   EOF
   

4. Test function:

   clj-nrepl-eval -p 7888 <<'EOF'
   (ns/my-fn ...)
   EOF
   

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