name: clj-nrepl description: REPL-driven Clojure development for writing, editing, and debugging code. Triggers when working with Clojure files (.clj, .cljs, .cljc, .edn), handling namespaces, functions, or tooling. Provides idiomatic functional programming guidance through the REPL workflow.

Clojure REPL-Driven Development

Tool Availability

Two tool sets provide nREPL evaluation. Prefer pi-clojure (native pi tools, direct TCP, no process-spawn overhead) when the extension is loaded. Fall back to the CLI tools otherwise.

Detecting availability:

• pi-clojure: clojure_eval appears in your tool list when the extension is loaded
• CLI tools: which clj-nrepl-eval / which clj-paren-repair

clj-paren-repair is preferred for file repair even when pi-clojure is loaded — it uses a real Clojure reader (edamame), parinfer-rust, and cljfmt.

Core Workflow

Never write code without REPL validation.

Every coding task follows this loop:

1. Gather context
2. Take action
3. Verify output

Before modifying any file:

1. Read existing code - Use read to examine target file and related files
2. Find port and verify connection — pi-clojure: clojure_find_nrepl_port then clojure_eval { port: PORT, code: "(+ 1 1)" }; CLI fallback: clj-nrepl-eval --discover-ports "(+ 1 1)"
3. Explore unfamiliar functions — eval (clojure.repl/doc function-name) via clojure_eval or clj-nrepl-eval
4. Test in REPL - Define and validate functions before saving
5. Check edge cases - nil, empty collections, invalid inputs
6. Save only after validation - Use edit or write
7. Reload before verifying edits — eval (require '[project.core] :reload) via clojure_eval or clj-nrepl-eval
8. Do not report success before verification - changed functions and relevant tests must pass

If nREPL fails, ask: "Please start your nREPL server (e.g., bb nrepl or lein repl :headless)"

Agent Loop

Use this loop for every coding task:

• Gather context - Read the target file, related code, call sites, dependencies, and tests
• Take action - Make the smallest focused change that solves the task; avoid unrelated refactors
• Verify output - Reload affected namespaces, test changed functions, validate edge cases, and run relevant tests

If verification fails, return to gather/action and fix the problem before reporting success.

Failure Recovery

If REPL evaluation, test execution, or namespace loading fails:

1. Read the exact error message
2. Isolate the failing expression or function
3. Fix the root cause
4. Reload affected namespaces
5. Rerun verification

If delimiter errors occur, use clj-paren-repair (files) or clojure_paren_repair (strings) instead of manual repair.

Task Communication

For multi-step tasks, briefly communicate:

• what you are reading
• what you are changing
• how you will verify it

Ask for clarification when requirements are ambiguous, multiple approaches have materially different trade-offs, or an architectural decision is required.

Essential Patterns

Threading Macros (always prefer over nesting)

;; -> for transformations
(-> user
    (assoc :last-login (now))
    (update :login-count inc))

;; ->> for sequences
(->> users
     (filter active?)
     (map :email)
     (str/join ", "))

;; some-> for nil-safe navigation
(some-> user :address :postal-code (subs 0 5))

;; cond-> for conditional changes
(cond-> request
  authenticated? (assoc :user current-user))

Naming Rules

Control Flow

;; when for side effects
(when (valid? data)
  (log "Processing")
  (process data))

;; cond for multiple branches
(cond
  (< n 0) :negative
  (= n 0) :zero
  :else   :positive)

Docstrings (required for public functions)

(defn calculate-total
  "Calculate total price including tax.

   Args:
     price - base price (number)
     rate  - tax rate as decimal (0.08 = 8%)

   Returns:
     number - total price

   Example:
     (calculate-total 100 0.08) => 108"
  [price rate]
  ...)

Namespace Templates

JVM Clojure (.clj):

(ns project.module
  "Brief description."
  (:require
   [clojure.string :as str]
   [clojure.set :as set])
  (:import
   (java.time LocalDate)))

(set! *warn-on-reflection* true)

ClojureScript (.cljs) or cross-platform (.cljc):

(ns project.module
  "Brief description."
  (:require
   [clojure.string :as str]))

Tools

Eval — pi-clojure (preferred)

Available when the pi-clojure extension is loaded. Direct TCP to nREPL, no process-spawn overhead.

# Discover port (checks .nrepl-port, .shadow-cljs/nrepl.port, .cider-nrepl.port, then defaults)
clojure_find_nrepl_port {}

# Evaluate expressions
clojure_eval { port: PORT, code: "(+ 1 2 3)" }
clojure_eval { port: PORT, code: "(defn sum [nums] (reduce + nums))" }
clojure_eval { port: PORT, code: "(sum [1 2 3])" }

# Discover functions
clojure_eval { port: PORT, code: "(clojure.repl/dir clojure.string)" }
clojure_eval { port: PORT, code: "(clojure.repl/doc map)" }
clojure_eval { port: PORT, code: "(clojure.repl/apropos \"split\")" }
clojure_eval { port: PORT, code: "(clojure.repl/source filter)" }

# Load project code
clojure_eval { port: PORT, code: "(require '[project.core :as core] :reload)" }

# Evaluate in a specific namespace
clojure_eval { port: PORT, ns: "project.core", code: "(my-fn 42)" }

Eval — clj-nrepl-eval (fallback)

Use when clojure_eval is not in your tool list.

clj-nrepl-eval --discover-ports "(+ 1 2 3)"
clj-nrepl-eval -p PORT "(defn sum [nums] (reduce + nums))"
clj-nrepl-eval -p PORT "(clojure.repl/dir clojure.string)"
clj-nrepl-eval -p PORT "(clojure.repl/doc map)"
clj-nrepl-eval -p PORT "(require '[project.core :as core] :reload)"

Paren repair — clj-paren-repair (preferred for files)

Uses edamame + parinfer-rust + cljfmt: repairs and formats in place. Preferred even when pi-clojure is loaded.

clj-paren-repair src/core.clj
clj-paren-repair src/*.clj test/*.clj

Paren repair — clojure_paren_repair (string repair)

Available when pi-clojure is loaded. Use for string-based repair or when clj-paren-repair is unavailable.

clojure_paren_repair { code: "(defn foo [x]" }
clojure_paren_repair { code: "(defn foo [x])", check: true }

Never manually fix parenthesis errors — use one of the tools above.

Validation Checklist

Before saving any code:

• Tested happy path in REPL
• Tested nil handling
• Tested empty collection handling
• Used threading macros over deep nesting
• Added docstring if public function
• Checked naming conventions
• Code under 80 characters per line
• Closing parens on single line

Code Review Workflow

Before modifying code:

1. read the target file
2. bash: rg "require.*target.ns" --type clj - find related files
3. bash: rg "function-name" --type clj - find call sites
4. Review namespace imports and patterns
5. Match codebase conventions

Detailed References

• Tool usage: See references/tool-guide.md for complete documentation of all eval and paren-repair tools
• Idiomatic patterns: See references/idioms.md for threading macros, control flow, data structures, error handling, and anti-patterns

Load these references when you need:

• Detailed tool commands
• Advanced idioms or patterns
• Error handling examples
• Testing patterns
• Research citations