Imported from brdloush/livewire (skills/livewire/SKILL.md). Install upstream with npx skills add brdloush/livewire --skill livewire. Copyright stays with the author.

Livewire — Live nREPL probe for Spring Boot apps

Use this skill whenever working with a Spring Boot application that has Livewire on its classpath. Before answering any question about the running app's state, beans, database, or behaviour — try the live REPL first. A live answer from the JVM beats static analysis every time.

Session start behaviour

On skill load

Say exactly one line — nothing more:

Livewire skill loaded. Run lw-start to connect to a running app, or ask lw-help for an overview of what Livewire can do.

On lw-help (or any "what can Livewire do?" question)

Give a brief prose overview — no headers, no tables, no bullet soup:

Livewire connects Claude to a running Spring Boot app via nREPL. From there you can inspect beans, entities, and HTTP endpoints; run JPQL queries and raw SQL against the live database; trace SQL to hunt N+1 problems and hot-swap @Query JPQL without restarting; observe exactly what fields a service call writes using diff-entity; analyse call graphs to find blast radius or plan a service split; and generate realistic fake entity graphs for test data prototyping. Run lw-start to connect, or ask about any specific feature.

On successful lw-start

Present the result as a single brief paragraph — no tables, no bullet lists. Include: app name, Spring Boot version, Hibernate version, Java version, active profiles, database product+version, and port. Example:

Connected to bloated-shelf on port 7888 — Spring Boot 4.0.1 / Hibernate 7.2.0 / Java 25, profiles dev + seed. Database: PostgreSQL 16.9.

If lw-start finds no server, say so briefly and suggest the user start the app.

Trigger Rules

MUST read the referenced file BEFORE acting on any question matching the keyword. This is not optional — static knowledge is unreliable for live-app questions.

⚠️ Before you act — mandatory file reads

When your message contains any keyword from the table above, read the referenced file before doing anything else. This is not a suggestion — the file contains fixes to known traps (lazy results, Cartesian products, shell escaping) that will save you 10+ failed attempts.

If you skip the read and produce a wrong result, the most likely cause is that you missed something in the reference file that you already knew but forgot.

⚠️ N+1 HUNTING (keywords: N+1, n+1, slow query, query count)

Read references/n-plus-one-hunting.md before writing any trace expression. That file contains:

• The exact procedure for N+1 hunting (service method, not controller)
• Why jpa/jpa-query returns lazy results → wrap in doall or trace count is always 0
• The Cartesian product trap — JOIN FETCH on two collections duplicates rows
• The exact tool for each phase (lw-trace-nplus1 → hq/hot-swap-query! → hq/reset-all!)

Do not rely on memory. Read the file. Then act.

Reference files

Load these on demand — read the relevant file before working in that area:

Prerequisites

This skill relies on clj-nrepl-eval — a lightweight CLI from clojure-mcp-light that lets Claude evaluate Clojure expressions against a running nREPL server.

Install it once with bbin:

brew install babashka/brew/bbin

bbin install https://github.com/bhauman/clojure-mcp-light.git \
  --tag v0.2.1 \
  --as clj-nrepl-eval \
  --main-opts '["-m" "clojure-mcp-light.nrepl-eval"]'

Verify: clj-nrepl-eval --discover-ports

Zero-install attach via jshell

Livewire can also be injected into a running Spring Boot app without any build changes using the attach.jsh bootstrap script. This is useful for quick exploration of an app you didn't write, or for onboarding teammates who haven't added the dependency yet.

jshell
# then at the jshell prompt:
/open https://raw.githubusercontent.com/brdloush/livewire/refs/heads/main/attach.jsh

Or, for a local development build:

LIVEWIRE_BUNDLE_PATH=/path/to/livewire-attach-X.Y.Z.jar \
  jshell /path/to/attach.jsh

Requirements: the target JVM must be started with -XX:+EnableDynamicAgentLoading (Java 21+).

Available commands at the jshell prompt (all require a prior attach(N) call):

Tip: once attached, eval() gives full access to the Livewire API — eval("(trace/trace-sql (.getBooks (lw/bean \"bookController\")))") works exactly as it does in a full nREPL session.

⚠️ Dev/staging only — never attach to a JVM with real user data.

Workflow

1. Start the session — always run lw-start first:

   lw-start

   Discovers running nREPL servers and prints an app summary in one shot. The default port is 7888 and can be overridden with LW_PORT.

2. Verify the connection is live:

   clj-nrepl-eval -p 7888 "(require '[net.brdloush.livewire.core :as lw]) (lw/info)"

   Never use lw/bean-names for connection checks — it emits hundreds of names with no useful runtime information.

3. Namespaces are pre-aliased in the user ns — no manual require needed: lw, q, intro, trace, qw, hq, jpa, mvc, faker

4. Evaluate snippets iteratively:

   clj-nrepl-eval -p <port> "<clojure-code>"
   clj-nrepl-eval -p <port> --timeout 5000 "<clojure-code>"

5. Run independent read queries in parallel — fire unrelated clj-nrepl-eval calls in a single message to reduce wall-clock time. Only serialize when one result feeds into the next.

6. Present results readably:

   • Collections of maps → markdown table
   • Single map → inline key/value list
   • Scalars → inline code in prose

7. Hot-patching: Do not use :reload to pick up a newly built JAR — it re-reads the same old class on the classpath. Instead, evaluate the new ns form and function bodies directly.

8. After writing a source-code fix: remind the user that a restart may be required for structural changes (new methods, new beans). @Query JPQL changes are picked up automatically by the query-watcher on recompile.

Wrapper scripts

This skill ships named wrapper scripts in a bin/ subdirectory next to this SKILL.md.

Always use wrapper scripts for named operations (SQL, JPQL, trace, N+1, endpoints, beans, call graphs). They handle namespace requiring automatically and avoid shell escaping issues. Fall back to raw clj-nrepl-eval only for ad-hoc expressions that have no wrapper equivalent — for example, multi-step mapv calls or thunks for diff-entity.

The scripts are installed alongside this skill. Do not check for their existence — invoke them directly. If you ever need to locate them, find this SKILL.md file first: find ~ -path '*/livewire/SKILL.md' 2>/dev/null — the bin/ folder is right next to it.

Use them via their full path: ~/.claude/skills/livewire/bin/<script-name>. The port defaults to 7888 and can be overridden with LW_PORT.

⚠️ Prefer clj-nrepl-eval -p <port> over lw-eval for arbitrary expressions. Clojure characters like !, ?, -> / ->> can be misinterpreted by the shell when passed through lw-eval. Use dedicated wrapper scripts for named operations; for everything else call clj-nrepl-eval directly:

clj-nrepl-eval -p 7888 "(hq/reset-all!)"

API namespaces — quick reference

Read references/api-core.md for full details, patterns, and examples for any of these.

Essential examples

;; Full env + datasource summary — always run this first
(lw/info)
;; => {:application-name "bloated-shelf", :active-profiles ["dev" "seed"],
;;     :java-version "25.0.1", :spring-boot-version "4.0.1",
;;     :hibernate-version "7.2.0.Final",
;;     :datasource {:db-product "PostgreSQL 16.9", :jdbc-url "...", ...}}

;; Which repository beans exist?
(lw/find-beans-matching ".*Repository.*")
;; => ("bookRepository" "authorRepository" ...)

;; List all HTTP endpoints
(first (intro/list-endpoints))
;; => {:methods ["GET"], :paths ["/api/authors/{id}"], :controller "AuthorController", ...}

;; List all Hibernate entities (table names, FQNs)
(intro/list-entities)
;; => [{:name "Book", :class "com.example.Book", :table-name "book"} ...]

;; Inspect an entity's DB mappings before writing any query
(intro/inspect-entity "Book")
;; => {:table-name "book", :identifier {:name "id"}, :properties [...], :relations [...]}

# N+1 detection — always use the wrapper script, not raw trace/detect-n+1 calls
lw-trace-nplus1 '(lw/run-as ["user" "ROLE_MEMBER"] (.getBooksByGenreId (lw/bean "bookService") 1))'
# => {:suspicious-queries [{:sql "select ... from author ...", :count 20} ...], :total-queries 98, ...}

⚠️ Hibernate lazy loading — always convert inside the transaction

Returning a raw Hibernate entity from in-tx / in-readonly-tx will throw LazyInitializationException when the REPL tries to print it — the session is already closed. Always eagerly convert to a plain Clojure map inside the transaction boundary.

;; ❌ blows up — printed after session closes
(lw/in-readonly-tx
  (.findById (lw/bean "bookRepository") 1))

;; ✅ convert while the session is still open
(lw/in-readonly-tx
  (-> (.findById (lw/bean "bookRepository") 1)
      .get
      clojure.core/bean
      (select-keys [:id :title :isbn])))

⚠️ Critical pitfalls (inline — full list in references/pitfalls.md)

• Never call .findAll without a Pageable — may return millions of rows and hang the REPL.
• lw/run-as requires ["username" "ROLE_X"], not a bare string — "admin" only grants ROLE_USER+ROLE_ADMIN; any other role needs the vector form. Same ROLE_ prefix required for lw-call-endpoint.
• Always use lw/bean->map not clojure.core/bean — records return {} silently with clojure.core/bean.
• lw/bean SomeClass only resolves Spring beans, not JPA entities — use lw/find-beans-matching to find the repository.
• EntityManager is not a named bean — use (lw/bean jakarta.persistence.EntityManager) (type-based lookup).
• Bean name ≠ class name, and :controller from lw-list-endpoints is ALWAYS a FQN — never pass it directly to lw-call-endpoint or lw/bean. Derive the bean name by taking the simple class name and lowercasing the first letter: com.example.web.BookController → bookController. When in doubt, verify with lw-find-beans.
• Always use JPQL (lw-jpa-query) for data queries — raw SQL only for metadata, DDL, or unmapped tables. lw-jpa-query and lw-call-endpoint default to 10 rows; raw SQL has no limit so add one explicitly.
• Always inspect entities before writing any query — never guess table/column names.
• lw-eval mangles !, ?, -> in zsh — use clj-nrepl-eval -p 7888 directly for expressions with these characters.
• Never use hq/hot-swap-query! to test a hypothesis — it mutates JVM state for all callers until explicitly reset. To prove a candidate JPQL reduces N+1, use jpa/jpa-query wrapped in trace/trace-sql or lw-trace-nplus1 — zero side effects, no cleanup needed. Hot-swap is only for final end-to-end confirmation once the fix is already validated.
• jpa/jpa-query takes keyword args, not positional — correct form: (jpa/jpa-query jpql :page 0 :page-size 20). It does not support named query parameters (:genreId etc.); for parameterized JPQL use (lw/bean jakarta.persistence.EntityManager) directly.

For all other pitfalls (UUID args, optional params, @PreAuthorize, javax vs jakarta, timing warm-up, etc.), read references/pitfalls.md.