Clojure REPL Integration

This skill enables interaction with running Clojure systems via nREPL using the clj-nrepl-eval CLI tool.

Pre-flight Check

Run which clj-nrepl-eval. If not found, prompt user to run ./install.sh in this skills folder.

When to Use This Skill

Use this skill when you need to:

• Evaluate Clojure code in a running system
• Test functions without restarting the REPL
• Query database connections from the running system
• Inspect loaded namespaces and their vars
• Debug live application state
• Verify code changes work before committing

⚠️ CRITICAL: Reload After File Changes

After editing any Clojure file, you MUST reload it in the REPL for changes to take effect.

The REPL keeps the old code in memory until you explicitly reload. This is the #1 source of confusion when testing changes.

Reload Commands

# Reload a single namespace (most common)
clj-nrepl-eval -p <port> "(require '[banzai.some.namespace] :reload)"

# Reload namespace AND all its dependencies
clj-nrepl-eval -p <port> "(require '[banzai.some.namespace] :reload-all)"

Standard Workflow

1. Edit file - Make your code changes
2. Reload namespace - (require '[edited.namespace] :reload)
3. Test changes - Call functions to verify behavior

Example

# After editing components/content/src/banzai/content/interface.clj:
clj-nrepl-eval -p 64323 "(require '[banzai.content.interface] :reload)"

# Now test the updated function
clj-nrepl-eval -p 64323 "(banzai.content.interface/some-fn {:arg 1})"

When to Use :reload-all

Use :reload-all when:

• You changed multiple related namespaces
• You modified a namespace that others depend on
• Changes don't seem to take effect with :reload

Note: :reload-all is slower but more thorough.

Quick Reference

Workflow

1. Discover Available nREPL Servers

clj-nrepl-eval --discover-ports

Output example:

Discovered nREPL servers:

In current directory (/Users/jared/code/banzai-polylith):
  localhost:64323 (clj)

Total: 1 server

2. Evaluate Code

Basic evaluation:

clj-nrepl-eval -p 64323 "(+ 1 2 3)"

Multi-form evaluation:

clj-nrepl-eval -p 64323 "(require '[some.namespace :as ns]) (ns/some-fn)"

3. Common Operations

Check loaded namespaces:

clj-nrepl-eval -p <port> "(filter #(re-find #\"banzai\" %) (map str (all-ns)))"

Require and explore a namespace:

clj-nrepl-eval -p <port> "(require '[banzai.some.interface :as api]) (keys (ns-publics 'banzai.some.interface))"

Access Integrant system components:

clj-nrepl-eval -p <port> "(require '[integrant.repl.state :refer [system]]) (keys system)"

Query database (with datasource from system):

clj-nrepl-eval -p <port> "(def ds (:some.system/datasource integrant.repl.state/system))"
clj-nrepl-eval -p <port> "(with-open [conn (.getConnection ds)] ...)"

Key Features

• Persistent sessions: Namespace changes and defs persist between calls
• Auto-repair delimiters: Fixes mismatched parens/brackets before evaluation
• Auto-responsive guidance: Returns helpful error messages for LLMs
• Timeout support: Prevent hanging on long-running evaluations

Banzai-Specific Patterns

Access Running System

Most Banzai bases use Integrant. Access system components via:

clj-nrepl-eval -p <port> "(require '[integrant.repl.state :refer [system]])"
clj-nrepl-eval -p <port> "(keys system)"

Common system keys:

• :banzai.*.system/datasource - Database connection pool
• :banzai.*.system/jetty - HTTP server
• :banzai.*.system/router - Reitit router
• :banzai.*.system/handler - Ring handler

Test a Function

# Require the namespace
clj-nrepl-eval -p <port> "(require '[banzai.some.interface :as api])"

# Call the function
clj-nrepl-eval -p <port> "(api/some-function {:arg1 \"value\"})"

Debug Data

# Pretty print with tap
clj-nrepl-eval -p <port> "(tap> some-data)"

# Or use clojure.pprint
clj-nrepl-eval -p <port> "(require '[clojure.pprint :as pp]) (with-out-str (pp/pprint some-data))"

Troubleshooting

No REPL found:

• Ensure a Clojure REPL is running with nREPL server
• Check .nrepl-port file exists in project root
• Start REPL with: clojure -A:dev:<base-alias>

Namespace not found:

• The namespace may not be loaded yet
• Use (require '[namespace.name]) first

Timeout errors:

• Increase timeout: --timeout 10000 (10 seconds)
• Default is 2 minutes (120000ms)

Session state issues:

• Sessions persist; use (in-ns 'user) to reset namespace
• Or evaluate (ns user) to return to user namespace

Best Practices

1. Always discover ports first - Don't assume port numbers
2. Require namespaces explicitly - Don't assume they're loaded
3. Use timeouts for risky operations - Prevent hanging
4. Quote code properly - Use single quotes in bash, escape inner quotes
5. Check system state - Verify Integrant system is running before accessing components