Documentation for auto-start nREPL feature #101
Conversation
- Update README.md CLI options to document :start-nrepl-cmd and :parse-nrepl-port - Update CONFIG.md with new configuration options for auto-starting nREPL - Add example configuration file for auto-start feature - Clarify that auto-start requires launching from project directory - Emphasize usefulness for Claude Code and other CLI-based LLM tools
WalkthroughDocumentation updates add two configuration options (:start-nrepl-cmd and :parse-nrepl-port) to enable automatic nREPL startup and port discovery, revise README guidance and examples accordingly, and introduce an example EDN config demonstrating these options. No source code or public API declarations are changed. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Dev as Developer/CLI Tool
participant MCP as clojure-mcp
participant FS as Project Dir (.nrepl-port)
participant Proc as nREPL Process
Dev->>MCP: Launch with config
alt start-nrepl-cmd provided
MCP->>Proc: Run :start-nrepl-cmd (cwd=project-dir)
alt parse-nrepl-port=true
Proc-->>MCP: stdout announces port
MCP->>MCP: Parse port from stdout
else parse-nrepl-port=false
MCP->>MCP: Use configured :port
end
else start-nrepl-cmd not provided
MCP->>FS: Read .nrepl-port (if present)
alt .nrepl-port found
MCP->>MCP: Use discovered port
else .nrepl-port not found
MCP->>MCP: Use configured :port (required)
end
end
MCP->>Proc: Connect via nREPL on resolved port
Note over MCP,Proc: Lifecycle: MCP may manage Proc when it started it
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@hugoduncan Can you review these Docs changes for me? Tell me if they are accurate? |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
README.md (4)
232-244: Typo: “Riggrep” → “ripgrep”.Also standardize capitalization: “Ripgrep” (name) vs “ripgrep” (command). You use “ripgrep” elsewhere—stick with that.
-4. **Install Riggrep (Optional)**: [ripgrep](https://github.com/BurntSushi/ripgrep#installation) is a smart, fast file search tool that respects `.gitignore`. +4. **Install ripgrep (Optional)**: [ripgrep](https://github.com/BurntSushi/ripgrep#installation) is a smart, fast file search tool that respects `.gitignore`.
222-224: Typo in Slack channel name.“ai-assited-coding” → “ai-assisted-coding”.
-* The [#ai-assited-coding Channel the Clojurians Slack](https://clojurians.slack.com/archives/C068E9L5M2Q) is very active and where I spend a lot of time. +* The [#ai-assisted-coding channel on the Clojurians Slack](https://clojurians.slack.com/archives/C068E9L5M2Q) is very active and where I spend a lot of time.
104-110: Fix multiple typos/grammar.These are prominent and worth correcting.
-LLMs can definitely write Clojure. However, our the secret weapon is +LLMs can definitely write Clojure. However, our secret weapon is -the REPL and the fast focused feedback loop that it offers. +the REPL and the fast, focused feedback loop that it offers. -IMHO Clojure is an overwhemingly excellent langauge for LLM assisted +IMHO Clojure is an overwhelmingly excellent language for LLM-assisted development. All it needed was bit of a bridge... and this is what I've tried to create with ClojureMCP.
520-520: Typo: “Clod Code” → “Claude Code”.-... - cribbed a bunch from Clod Code +... - cribbed a bunch from Claude Code
🧹 Nitpick comments (7)
CONFIG.md (2)
42-46: Good addition; call out stdout-only parsing explicitly here too.This matches the project preference to only parse stdout for port discovery. Consider adding “stdout-only” wording to the “Important” paragraph so readers don’t assume stderr is parsed.
-**Important**: This feature requires the MCP server to be launched from your project directory ... +**Important**: This feature requires the MCP server to be launched from your project directory ... +Only stdout is parsed for nREPL port discovery; stderr is ignored.
64-69: Mention .nrepl-port as a fallback when stdout lacks a port line.This avoids confusion for commands that don’t announce on stdout.
-**Note:** When `:parse-nrepl-port` is `false`, you must provide the `:port` configuration. +**Note:** When `:parse-nrepl-port` is `false`, you must provide the `:port` configuration. If your start command does not print the port to stdout, either rely on an existing `.nrepl-port` file in the project root or set `:parse-nrepl-port false` and specify `:port`.resources/configs/example-auto-start-nrepl.edn (1)
16-19: Suggest documenting the .nrepl-port fallback.Some startup commands may not announce on stdout.
;; Port is optional when :parse-nrepl-port is true ;; Required when :parse-nrepl-port is false -;; :port 7888 +;; If your command doesn't print the port to stdout, you can rely on a `.nrepl-port` file in the project root instead. +;; :port 7888README.md (4)
983-989: Minor: with default=true you can omit :parse-nrepl-port true in examples.Optional, but simplifies the quickstart lines.
-# With automatic nREPL server startup and port discovery -# Perfect for Claude Code - run this from your project directory -clojure -X:mcp :start-nrepl-cmd '["lein" "repl" ":headless"]' :parse-nrepl-port true +# With automatic nREPL server startup and port discovery (run from your project directory) +clojure -X:mcp :start-nrepl-cmd '["lein" "repl" ":headless"]' ... -# For Claude Code with Clojure projects (from project directory) -clojure -X:mcp :start-nrepl-cmd '["clojure" "-M:nrepl"]' :parse-nrepl-port true +# For Claude Code with Clojure projects (from project directory) +clojure -X:mcp :start-nrepl-cmd '["clojure" "-M:nrepl"]'
115-118: Grammar: “develop experience” → “development experience”.Minor polish in the Overview.
-Clojure develop experience. +Clojure development experience.
126-129: Grammar: “let's you” → “lets you” (twice).Contractions here are incorrect.
-Claude Desktop, also let's you have quick access +Claude Desktop also lets you have quick access - Claude Desktop also let's you see the complete reasoning and tool + Claude Desktop also lets you see the complete reasoning and tool
1045-1054: Security phrasing: keep the warning but tighten wording.Clearer that bash can escape path restrictions.
-- the Bash tool doesn't respect these boundaries so be wary +- The Bash tool does not enforce these directory boundaries; use with care.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
CONFIG.md(1 hunks)README.md(3 hunks)resources/configs/example-auto-start-nrepl.edn(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-08-18T00:39:24.837Z
Learnt from: hugoduncan
PR: bhauman/clojure-mcp#86
File: src/clojure_mcp/subprocess.clj:0-0
Timestamp: 2025-08-18T00:39:24.837Z
Learning: In the clojure-mcp project, the user prefers to only parse stdout for nREPL port discovery in the subprocess.clj module, and explicitly does not want to parse stderr for port information.
Applied to files:
resources/configs/example-auto-start-nrepl.ednCONFIG.mdREADME.md
🔇 Additional comments (5)
CONFIG.md (1)
47-51: Examples look good.Covering Leiningen, Clojure CLI, and Babashka is helpful.
resources/configs/example-auto-start-nrepl.edn (1)
28-35: Potential gotcha: verify these starters announce to stdout.Lein, Clojure CLI, and bb may differ in which stream they announce the port on. A short note here to verify stdout would save setup time.
Would you confirm whether each of these prints the port to stdout in your environment? If any print to stderr or not at all, we should add a note recommending
.nrepl-portor explicit:port.README.md (3)
936-939: Good: makes :port optional with auto-start + port parsing.This sets user expectations correctly. No change needed.
990-992: Good: explicit-port example is clear.Keeps the alternative path obvious.
999-1001: Nice: document .nrepl-port fallback.This complements auto-discovery well.
| ### `:parse-nrepl-port` | ||
| **Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats. | ||
|
|
||
| **Available values:** | ||
| - `true` (default when `:start-nrepl-cmd` is provided) - Parse port from nREPL output | ||
| - `false` - Don't parse port; requires `:port` to be explicitly provided | ||
|
|
There was a problem hiding this comment.
Default mismatch with README; align on a single truth and clarify stdout-only.
CONFIG.md says default is true when :start-nrepl-cmd is provided, but README says default is false. Recommend making the default “true when :start-nrepl-cmd is set” in both places and reiterating stdout-only behavior to match project preference.
-**Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats.
+**Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout (stdout-only) output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats.
...
-`true` (default when `:start-nrepl-cmd` is provided) - Parse port from nREPL output
+`true` (default when `:start-nrepl-cmd` is provided) - Parse port from nREPL stdout📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### `:parse-nrepl-port` | |
| **Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats. | |
| **Available values:** | |
| - `true` (default when `:start-nrepl-cmd` is provided) - Parse port from nREPL output | |
| - `false` - Don't parse port; requires `:port` to be explicitly provided | |
| ### `:parse-nrepl-port` | |
| **Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout (stdout-only) output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats. | |
| **Available values:** | |
| - `true` (default when `:start-nrepl-cmd` is provided) - Parse port from nREPL stdout | |
| - `false` - Don't parse port; requires `:port` to be explicitly provided |
🤖 Prompt for AI Agents
In CONFIG.md around lines 57-63, the documented default for `:parse-nrepl-port`
conflicts with README (CONFIG.md says default true when `:start-nrepl-cmd` is
provided, README says false) and the stdout-only behavior is not reiterated;
update CONFIG.md and README to agree that the default is “true when
`:start-nrepl-cmd` is set”, and add a short clarifying sentence in both files
that parsing only inspects the command's stdout (not stderr or other channels),
so both docs present the same default and explicitly state stdout-only behavior.
| #### `:start-nrepl-cmd` | ||
| **Optional** - A command to automatically start an nREPL server if one is not already running. Must be specified as a vector of strings. The MCP server will start this process and manage its lifecycle. | ||
|
|
||
| **Important**: This option requires launching `clojure-mcp` from your project directory (where your `deps.edn` or `project.clj` is located). The nREPL server will be started in the current working directory. This is particularly useful for Claude Code and other command-line LLM clients where you want automatic nREPL startup without manual process management. | ||
|
|
||
| `:start-nrepl-cmd ["lein" "repl" ":headless"]` or `:start-nrepl-cmd ["clojure" "-M:nrepl"]` | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Clarify location requirement applies only to auto-start mode.
Avoid contradiction with “Location Independence” later in the doc.
-**Important**: This option requires launching `clojure-mcp` from your project directory (where your `deps.edn` or `project.clj` is located). The nREPL server will be started in the current working directory. This is particularly useful for Claude Code and other command-line LLM clients where you want automatic nREPL startup without manual process management.
+**Important (auto-start mode only)**: When using `:start-nrepl-cmd`, you must launch `clojure-mcp` from your project directory (where your `deps.edn` or `project.clj` is located). The nREPL server is started in the current working directory. Outside of auto-start mode, you can run the MCP server from any directory. This is particularly useful for Claude Code and other CLI LLM clients where you want automatic nREPL startup without manual process management.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| #### `:start-nrepl-cmd` | |
| **Optional** - A command to automatically start an nREPL server if one is not already running. Must be specified as a vector of strings. The MCP server will start this process and manage its lifecycle. | |
| **Important**: This option requires launching `clojure-mcp` from your project directory (where your `deps.edn` or `project.clj` is located). The nREPL server will be started in the current working directory. This is particularly useful for Claude Code and other command-line LLM clients where you want automatic nREPL startup without manual process management. | |
| `:start-nrepl-cmd ["lein" "repl" ":headless"]` or `:start-nrepl-cmd ["clojure" "-M:nrepl"]` | |
| #### `:start-nrepl-cmd` | |
| **Optional** - A command to automatically start an nREPL server if one is not already running. Must be specified as a vector of strings. The MCP server will start this process and manage its lifecycle. | |
| **Important (auto-start mode only)**: When using `:start-nrepl-cmd`, you must launch `clojure-mcp` from your project directory (where your `deps.edn` or `project.clj` is located). The nREPL server is started in the current working directory. Outside of auto-start mode, you can run the MCP server from any directory. This is particularly useful for Claude Code and other CLI LLM clients where you want automatic nREPL startup without manual process management. | |
| `:start-nrepl-cmd ["lein" "repl" ":headless"]` or `:start-nrepl-cmd ["clojure" "-M:nrepl"]` |
🤖 Prompt for AI Agents
In README.md around lines 945 to 951, the text implies a directory requirement
that contradicts the later “Location Independence” section; clarify that the
working-directory requirement applies only when using the :start-nrepl-cmd
auto-start option. Update the paragraph to explicitly state: when you provide
:start-nrepl-cmd, MCP must be launched from your project directory because the
nREPL server is started in the current working directory; otherwise MCP remains
location-independent and no special working directory is required. Keep the
examples and mention that this only affects auto-start mode.
| **Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout output. Defaults to `false`. The parser recognizes common nREPL port announcement formats. | ||
|
|
||
| `:parse-nrepl-port true` | ||
|
|
There was a problem hiding this comment.
Fix default to match CONFIG.md and clarify stdout-only parsing.
Current text says default is false; CONFIG.md says default true when :start-nrepl-cmd is set. Recommend align to true-when-present and mention stdout-only.
-**Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout output. Defaults to `false`. The parser recognizes common nREPL port announcement formats.
+**Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout (stdout-only) output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout output. Defaults to `false`. The parser recognizes common nREPL port announcement formats. | |
| `:parse-nrepl-port true` | |
| **Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout (stdout-only) output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats. | |
| `:parse-nrepl-port true` |
🤖 Prompt for AI Agents
In README.md around lines 953 to 956, the doc incorrectly states the default for
:parse-nrepl-port is false; update it to say the default is true when
:start-nrepl-cmd is set (otherwise false), and explicitly state that the parser
only inspects the command's stdout for nREPL port announcements; keep the
example but adjust the preceding sentence to reflect the corrected default and
stdout-only parsing behavior.
| ;; Parse the port from nREPL output (default: true when :start-nrepl-cmd is provided) | ||
| ;; Set to false if you want to use a fixed port specified below | ||
| :parse-nrepl-port true | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Clarify stdout-only parsing and implied default.
Match the docs: stdout-only, and default true when :start-nrepl-cmd is present.
-;; Parse the port from nREPL output (default: true when :start-nrepl-cmd is provided)
+;; Parse the port from nREPL stdout only (default: true when :start-nrepl-cmd is provided)
;; Set to false if you want to use a fixed port specified below
:parse-nrepl-port true📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ;; Parse the port from nREPL output (default: true when :start-nrepl-cmd is provided) | |
| ;; Set to false if you want to use a fixed port specified below | |
| :parse-nrepl-port true | |
| ;; Parse the port from nREPL stdout only (default: true when :start-nrepl-cmd is provided) | |
| ;; Set to false if you want to use a fixed port specified below | |
| :parse-nrepl-port true |
🤖 Prompt for AI Agents
In resources/configs/example-auto-start-nrepl.edn around lines 12 to 15, the
comment for :parse-nrepl-port should be clarified to state that port parsing
reads only stdout and that the option defaults to true when :start-nrepl-cmd is
provided; update the comment text to explicitly mention "stdout-only" parsing
and that the default is true if :start-nrepl-cmd is set (and advise setting to
false to use a fixed port).
Summary
This PR adds comprehensive documentation for the new auto-start nREPL feature introduced in #86.
Changes
Documentation Updates
README.md:
:start-nrepl-cmdand:parse-nrepl-port:portfrom required to optional (when using auto-start with port discovery)CONFIG.md:
New Example Configuration:
resources/configs/example-auto-start-nrepl.ednKey Clarifications
Related
Testing
Documentation-only changes, no code modifications.
Summary by CodeRabbit