{"id":30123414,"url":"https://github.com/licht1stein/brepl","last_synced_at":"2026-02-17T19:09:13.097Z","repository":{"id":298076835,"uuid":"998783650","full_name":"licht1stein/brepl","owner":"licht1stein","description":"Bracket-fixing Clojure REPL for Claude Code, ECA and other agents.","archived":false,"fork":false,"pushed_at":"2026-02-08T15:29:38.000Z","size":272,"stargazers_count":25,"open_issues_count":1,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-08T22:03:31.996Z","etag":null,"topics":["ai","babashka","claude-code","claude-hooks","clojure","eca","interactive-development","nrepl","nrepl-client","repl","repl-driven","repl-driven-development"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/licht1stein.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-06-09T08:42:06.000Z","updated_at":"2026-02-08T15:30:05.000Z","dependencies_parsed_at":"2025-08-10T14:53:39.499Z","dependency_job_id":null,"html_url":"https://github.com/licht1stein/brepl","commit_stats":null,"previous_names":["licht1stein/brepl"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/licht1stein/brepl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/licht1stein%2Fbrepl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/licht1stein%2Fbrepl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/licht1stein%2Fbrepl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/licht1stein%2Fbrepl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/licht1stein","download_url":"https://codeload.github.com/licht1stein/brepl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/licht1stein%2Fbrepl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29554511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T18:16:07.221Z","status":"ssl_error","status_checked_at":"2026-02-17T18:16:04.782Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","babashka","claude-code","claude-hooks","clojure","eca","interactive-development","nrepl","nrepl-client","repl","repl-driven","repl-driven-development"],"created_at":"2025-08-10T14:41:06.525Z","updated_at":"2026-02-17T19:09:08.087Z","avatar_url":"https://github.com/licht1stein.png","language":"Clojure","readme":"# brepl\n\n[![GitHub release](https://img.shields.io/github/v/release/licht1stein/brepl?label=version)](https://github.com/licht1stein/brepl/releases/latest)\n[![Run Tests](https://github.com/licht1stein/brepl/actions/workflows/test.yml/badge.svg)](https://github.com/licht1stein/brepl/actions/workflows/test.yml)\n\n**B**racket-fixing **REPL** for AI-assisted Clojure development.\n\n## What is brepl?\n\n**brepl** (Bracket-fixing REPL) enables AI-assisted Clojure development by solving the notorious parenthesis problem. It fully supports [Claude Code](https://claude.ai/claude-code) and [ECA](https://eca.dev) (Editor Code Assistant) through their hook systems, providing three essential capabilities:\n\n1. **🔧 Automatic bracket fixing** - Intelligently corrects mismatched parentheses, brackets, and braces using [parmezan](https://github.com/borkdude/parmezan)\n2. **⚡ Simple REPL evaluation** - Gives AI agents a straightforward way to evaluate code in your running REPL, enabling truly interactive development\n3. **🔄 Live file synchronization** - Automatically evaluates edited files in the REPL, providing early feedback on evaluation errors before they become problems\n\n**Primary use case:** Claude Code, ECA, and other AI coding agents that need reliable Clojure syntax handling and immediate REPL feedback.\n\n**Versatile tool:** While designed for AI workflows, brepl is equally capable as a lightweight CLI nREPL client for one-shot evaluations, scripts, and automation—making it useful for both AI-assisted and traditional development workflows.\n\n### Bracket Auto-Fix\n\nbrepl uses [parmezan](https://github.com/borkdude/parmezan) for intelligent bracket correction:\n\n- **Pure Clojure**: No external binary dependencies required\n- **Automatic fixing**: Corrects mismatched delimiters, missing brackets, and extra closing parens\n- **Graceful fallback**: Blocks with syntax errors when auto-fix is not possible\n\n## Quick Start\n\n### For AI-Assisted Development with Claude Code\n\nAssuming brepl is already installed (see [Installation](#installation)):\n\n```bash\n# Start your nREPL server\nbb nrepl-server\n\n# Install hooks and skill in your project\nbrepl hooks install\n```\n\nThe `brepl hooks install` command configures Claude Code to:\n\n- Validate and auto-fix brackets before every file edit\n- Evaluate changed Clojure files in your running REPL after edits\n- Provide immediate feedback on syntax and evaluation errors\n- Install the brepl skill that teaches Claude:\n  - Heredoc pattern for reliable code evaluation\n  - Error recovery workflows\n\nNow Claude can write Clojure code confidently without worrying about parentheses or missing REPL feedback.\n\n### For ECA (Editor Code Assistant)\n\nbrepl fully supports [ECA](https://eca.dev) ([GitHub](https://github.com/editor-code-assistant/eca)), an open source editor-agnostic AI pair programming tool:\n\n```bash\n# Start your nREPL server\nbb nrepl-server\n\n# Install ECA hooks in your project\nbrepl eca install\n```\n\nThe `brepl eca install` command configures ECA via `.eca/config.json` with the same capabilities as Claude Code hooks—bracket validation, auto-fix, and REPL evaluation.\n\n### For Command-Line Usage\n\n```bash\n# Evaluate expressions (auto-detects .nrepl-port)\nbrepl -e '(+ 1 2 3)'\n# =\u003e 6\n\n# Load and execute files\nbrepl -f script.clj\n\n# Bracket fixing is automatic in hook mode\n```\n\n## Features\n\n### Core Capabilities for AI-Assisted Development\n\n#### 🔧 Bracket Fixing\n\n- **Intelligent auto-correction** - Uses parmezan to fix mismatched delimiters automatically\n- **Pre-edit validation** - Catches and fixes bracket problems before they're written to files\n- **Detailed error reporting** - When auto-fix isn't possible, provides clear syntax errors for AI agents\n- **No external dependencies** - Pure Clojure solution, no binary installation required\n\n#### ⚡ Simple REPL Evaluation\n\n- **Direct nREPL integration** - AI agents can evaluate code in your running REPL with simple commands\n- **Heredoc pattern** - Skill teaches reliable evaluation pattern that eliminates shell quoting issues\n- **Automatic bracket correction** - Bracket errors are fixed automatically in hook mode\n- **Project-aware discovery** - Automatically finds the right REPL for each file (v1.3.0)\n- **Full protocol support** - Access any nREPL operation, not just evaluation\n- **Fast Babashka runtime** - Instant startup for responsive AI interactions\n\n#### 🔄 Live File Synchronization\n\n- **Automatic evaluation** - Files are evaluated in REPL immediately after editing\n- **Early error feedback** - AI agents see evaluation errors right away, not later\n- **Session-based backups** - Automatic backup/restore protects against bad edits\n- **One-command setup** - `brepl hooks install` enables everything in seconds\n\n### Versatile CLI Client\n\n- 🚀 **Fast command-line evaluation** - Quick one-liners with `brepl -e '(+ 1 2)'`\n- 📁 **File loading** - Execute entire Clojure files with `brepl -f script.clj`\n- 💬 **Raw nREPL messages** - Send any protocol message for advanced operations\n- 🔍 **Smart port discovery** - Automatically detects `.nrepl-port` files\n- ⚙️ **Flexible configuration** - Environment variables and CLI arguments\n- 🐛 **Proper error handling** - Shows exceptions and stack traces\n- 📊 **Verbose mode** - Debug nREPL communication with `--verbose`\n\n## Installation\n\n### Option 1: Install via bbin (recommended)\n\n```bash\nbbin install io.github.licht1stein/brepl\n```\n\n### Option 2: Direct download (curl)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/licht1stein/brepl/master/brepl -o ~/.local/bin/brepl\nchmod +x ~/.local/bin/brepl\n```\n\n### Option 3: Install with Nix\n\n```nix\n{ pkgs ? import \u003cnixpkgs\u003e {} }:\n\nlet\n  brepl = pkgs.callPackage (pkgs.fetchFromGitHub {\n    owner = \"licht1stein\";\n    repo = \"brepl\";\n    rev = \"v2.7.0\";\n    hash = \"sha256-eTQS5LvAOLvx46YS6V/2+bYkWSELTTwZ1ir77eLk99M=\";\n  } + \"/package.nix\") {};\nin\npkgs.mkShell {\n  buildInputs = [ brepl ];\n}\n```\n\nThen run `nix-shell` to enter a shell with brepl available.\n\n### Option 4: Manual Installation\n\n```bash\ngit clone https://github.com/licht1stein/brepl.git\ncd brepl\n\n# Add to PATH\nln -s $(pwd)/brepl ~/.local/bin/brepl\n```\n\n## Usage\n\n**Get help:** `brepl --help`\n\n### Command Line Options\n\n```\n  -e, --e          \u003cexpr\u003e     Expression to evaluate\n  -f, --f          \u003cfile\u003e     File to load and execute\n  -m, --m, --message \u003cmessage\u003e Raw nREPL message (EDN format)\n  -h, --h          \u003chost\u003e     nREPL host (default: localhost or BREPL_HOST)\n  -p, --p          \u003cport\u003e     nREPL port (required - auto-detects from .nrepl-port or BREPL_PORT)\n      --verbose              Show raw nREPL messages instead of parsed output\n      --version              Show brepl version\n  -?, --help                 Show help message\n```\n\n### Hook Subcommands\n\n```bash\nbrepl hooks install              # Install hooks to .claude/settings.local.json (includes skill)\nbrepl hooks uninstall            # Remove hooks\nbrepl hooks validate \u003cfile\u003e \u003ccontent\u003e  # Pre-edit validation with auto-fix\nbrepl hooks eval \u003cfile\u003e          # Post-edit evaluation\nbrepl hooks stop                 # Run stop hooks from .brepl/hooks.edn\nbrepl hooks session-end          # Cleanup session backups (reads JSON from stdin)\n```\n\n**Note**: `hook` works as an alias for `hooks` for backward compatibility.\n\n### Skill Commands\n\n```bash\nbrepl skill install             # Install brepl skill to .claude/skills/brepl\nbrepl skill uninstall           # Remove brepl skill\n```\n\n**Note**: The skill is automatically installed when you run `brepl hooks install`. Use `brepl skill install` only if you want to install the skill separately without hooks.\n\n**What the skill teaches Claude:**\n\n- Heredoc pattern for reliable code evaluation\n- In-place file fixing workflows\n- Error recovery patterns\n\n```bash\n\n```\n\n**Examples:**\n\n```bash\n# Fix brackets in an expression\n# =\u003e (defn foo [])\n\n# Fix brackets in a file\n\n```\n\n### Basic Usage\n\n```bash\n# Evaluate an expression (auto-detects port from .nrepl-port)\nbrepl -e '(+ 1 2 3)'\n\n# Load and execute a file\nbrepl -f script.clj\n\n# Use single quotes to avoid escaping double quotes\nbrepl -e '(println \"Hello, World!\")'\n```\n\n### Heredoc Pattern for Reliable Evaluation\n\nFor AI agents (and humans) working with Clojure code that contains complex quoting, multi-line expressions, or nested structures, the heredoc pattern provides a consistent, foolproof approach to evaluation:\n\n```bash\n# Standard heredoc pattern - works for all cases\nbrepl \u003c\u003c'EOF'\n(require '[clojure.string :as str])\n(str/join \", \" [\"a\" \"b\" \"c\"])\nEOF\n```\n\n**Why use heredoc?**\n\n- **No quoting issues**: Everything between `\u003c\u003c'EOF'` and `EOF` is treated as literal input\n- **Consistent pattern**: One approach for all evaluations, from simple to complex\n- **Multi-line friendly**: Natural formatting for readable code\n- **Easy to extend**: Add more forms without changing syntax\n\n**Examples:**\n\n```bash\n# Multi-line expressions with complex quoting\nbrepl \u003c\u003c'EOF'\n(println \"String with 'single' and \\\"double\\\" quotes\")\n(+ 10 20)\nEOF\n\n# Namespace reloading and testing\nbrepl \u003c\u003c'EOF'\n(require '[myapp.core] :reload)\n(myapp.core/some-function \"test\" 123)\nEOF\n\n# Data structures with nested quotes\nbrepl \u003c\u003c'EOF'\n(def config\n  {:database {:host \"localhost\"\n              :port 5432}\n   :api {:key \"secret-key\"}})\n(println (:database config))\nEOF\n```\n\n**Note**: Always use `\u003c\u003c'EOF'` (with single quotes) to prevent shell variable expansion. The brepl skill (installed via `brepl hooks install`) teaches Claude Code to use this pattern automatically.\n\n### Port Configuration\n\nThe **port is required** and resolved in this order:\n\n1. **Command line:** `-p 7888`\n2. **Auto-detect:** `.nrepl-port` file\n   - For `-f` flag: searches from the file's directory upward (v1.3.0+)\n   - For `-e`/`-m` flags: uses current directory\n3. **Environment:** `BREPL_PORT=7888`\n\n```bash\n# Explicit port\nbrepl -p 7888 -e '(+ 1 2)'\n\n# Using environment variable\nBREPL_PORT=7888 brepl -e '(+ 1 2)'\n\n# Auto-detect from .nrepl-port (most common)\nbrepl -e '(+ 1 2)'\n\n# NEW in v1.3.0: File-based project detection\n# If you have multiple projects with different nREPL servers:\n#   project1/.nrepl-port (port 7000)\n#   project2/.nrepl-port (port 8000)\nbrepl -f project1/src/core.clj  # Uses port 7000\nbrepl -f project2/src/app.clj   # Uses port 8000\n```\n\n#### Project-Aware Port Discovery (v1.3.0+)\n\nWhen using the `-f` flag, brepl now searches for `.nrepl-port` files starting from the file's directory and walking up the directory tree. This allows you to work with multiple projects simultaneously:\n\n```bash\n# Directory structure:\n# ~/projects/\n#   ├── backend/\n#   │   ├── .nrepl-port (7000)\n#   │   └── src/api/handler.clj\n#   └── frontend/\n#       ├── .nrepl-port (8000)\n#       └── src/ui/core.cljs\n\n# Automatically uses the correct nREPL server for each project:\nbrepl -f ~/projects/backend/src/api/handler.clj    # Connects to port 7000\nbrepl -f ~/projects/frontend/src/ui/core.cljs      # Connects to port 8000\n```\n\nThis is especially useful when:\n\n- Working with monorepos containing multiple services\n- Switching between different projects frequently\n- Using editor integrations that operate on individual files\n\n### Remote Connections\n\n```bash\n# Connect to remote host with specific port\nbrepl -h remote-server -p 7888 -e '(+ 1 2)'\n\n# Using environment variables\nBREPL_HOST=remote-server BREPL_PORT=7888 brepl -e '(+ 1 2)'\n```\n\n## Environment Variables\n\nSet these for default configuration:\n\n```bash\nexport BREPL_HOST=localhost  # Default host\nexport BREPL_PORT=7888       # Default port\n```\n\nOr use them for one-off commands:\n\n```bash\nBREPL_PORT=7888 brepl -e '(+ 1 2 3)'\n```\n\n## Examples\n\n```bash\n# Start nREPL server (creates .nrepl-port file)\nbb nrepl-server\n\n# Basic evaluation\nbrepl -e '(+ 1 2 3)'\nbrepl -e '(require '[clojure.string :as str]) (str/upper-case \"hello\")'\n\n# Load a script file\nbrepl -f my-script.clj\n\n# Send raw nREPL messages\nbrepl -m '{\"op\" \"describe\"}'\nbrepl -m '{\"op\" \"ls-sessions\"}'\nbrepl -m '{\"op\" \"eval\" \"code\" \"(+ 1 2)\"}'\n\n# Multi-line expressions (single quotes make it easier)\nbrepl -e '(let [x 10\n               y 20]\n           (+ x y))'\n\n# Quick math\nbrepl -e '(reduce + (range 100))'\n\n# Check Babashka version\nbrepl -e '(System/getProperty \"babashka.version\")'\n\n# Development workflow\nbrepl -f test/my_test.clj\nbrepl -e '(require '[my.namespace :refer :all]) (my-function 123)'\n```\n\n## Advanced Usage\n\n### Raw nREPL Messages\n\nThe `-m/--message` option allows you to send raw nREPL messages in EDN format. This makes brepl a full-fledged nREPL client capable of accessing all operations supported by the nREPL server.\n\n```bash\n# Get server capabilities\nbrepl -m '{\"op\" \"describe\"}'\n\n# List active sessions\nbrepl -m '{\"op\" \"ls-sessions\"}'\n\n# Clone a session\nbrepl -m '{\"op\" \"clone\"}'\n\n# Get completions\nbrepl -m '{\"op\" \"complete\" \"prefix\" \"str/\" \"ns\" \"user\"}'\n\n# Look up symbol documentation\nbrepl -m '{\"op\" \"info\" \"symbol\" \"map\" \"ns\" \"clojure.core\"}'\n\n# Evaluate with specific session\nbrepl -m '{\"op\" \"eval\" \"code\" \"(+ 1 2)\" \"session\" \"your-session-id\"}'\n```\n\n#### Common nREPL Operations\n\n- `describe` - Returns server capabilities and supported operations\n- `eval` - Evaluate code\n- `load-file` - Load a file's contents\n- `ls-sessions` - List active sessions\n- `clone` - Create a new session\n- `close` - Close a session\n- `interrupt` - Interrupt an evaluation\n- `complete` - Get code completions\n- `info` - Get symbol information\n- `lookup` - Look up symbol documentation\n- `eldoc` - Get function signature information\n\nFor a complete list of standard nREPL operations, see the [nREPL documentation](https://nrepl.org/nrepl/ops.html).\n\n#### Tips for Raw Messages\n\n1. **Automatic ID generation**: If you don't provide an `id` field, brepl will add one automatically\n2. **Response handling**: Some operations return multiple messages. Use `--verbose` to see the full conversation\n3. **Session management**: Most operations work without a session, but some require one (like `interrupt`)\n4. **Byte array conversion**: All byte arrays in responses are automatically converted to strings for readability\n5. **Debugging**: Use `--verbose` with `-m` to see exactly what's sent and received\n\n```bash\n# Debug mode - see full message exchange\nbrepl -m '{\"op\" \"describe\"}' --verbose\n```\n\n### AI-Assisted Development with Claude Code\n\nbrepl is specifically designed to integrate with [Claude Code](https://claude.ai/claude-code) through its hook system, providing seamless REPL-driven development for AI agents.\n\n**Why brepl for Claude Code?**\n\nClaude (and other LLMs) often struggle with Lisp parentheses, leading to syntax errors that break the development flow. brepl solves this by intercepting Claude's file operations and:\n\n1. Fixing bracket errors before they're written to disk\n2. Evaluating code in your REPL immediately after edits\n3. Providing clear feedback so Claude can correct course quickly\n\n**Two Approaches to AI-Assisted Clojure:**\n\n1. **Protocol servers** - Run MCP servers, configure protocol bridges, manage multiple processes\n2. **brepl hooks** - Direct integration with Claude Code using your existing REPL (our approach)\n\n#### Quick Setup for Claude Code\n\nThe `brepl hooks install` command configures your project for Claude Code by creating or updating `.claude/settings.local.json`:\n\n```bash\n# In your Clojure project directory:\nbrepl hooks install\n```\n\nThis installs three hooks that run automatically during Claude Code sessions:\n\n- **Pre-edit hook**: Intercepts Claude's file writes, validates syntax, and auto-fixes brackets\n- **Post-edit hook**: Evaluates the edited file in your REPL and reports any runtime errors\n- **Session cleanup**: Removes temporary backup files when Claude Code session ends\n\nOnce installed, Claude can edit your Clojure files without worrying about parentheses, and you'll see immediate REPL feedback for every change.\n\n#### Hook Commands\n\n**`brepl hooks install`**\nCreates or updates `.claude/settings.local.json` to configure Claude Code hooks for the current project. This file tells Claude Code to run brepl for validation and evaluation on every Clojure file edit. Idempotent—safe to run multiple times.\n\n**`brepl hooks validate \u003cfile\u003e \u003ccontent\u003e`**\nPre-edit syntax validation with automatic bracket correction. Recursively closes unclosed brackets and braces using the edamame parser. Returns corrected code or blocks with detailed error messages.\n\n```bash\n# Auto-fixes unclosed brackets\nbrepl hooks validate src/core.clj \"(defn foo [\"\n# =\u003e {\"decision\":\"allow\",\"correction\":\"(defn foo [])\"}\n\n# Blocks unfixable syntax errors\nbrepl hooks validate src/core.clj \"\\\"unclosed string\"\n# =\u003e {\"decision\":\"block\",\"reason\":\"Syntax error...\"}\n```\n\n**`brepl hooks eval \u003cfile\u003e`**\nPost-edit validation and optional nREPL evaluation. Validates syntax first, then evaluates via nREPL if available. Warnings don't block—development stays fluid while catching real errors.\n\n```bash\n# With nREPL running - evaluates and warns on errors\nbrepl hooks eval src/core.clj\n# =\u003e {\"decision\":\"allow\",\"warning\":\"Undefined symbol...\"}\n\n# Without nREPL - validates syntax only\nbrepl hooks eval src/core.clj\n# =\u003e {\"decision\":\"allow\"}  # Graceful degradation\n```\n\n**`brepl hooks uninstall`**\nRemoves hooks from `.claude/settings.local.json` cleanly.\n\n**`brepl hooks session-end`**\nCleanup command (called automatically by Claude Code) that removes session backup files. Reads JSON from stdin.\n\n#### How It Works\n\nWhen active, brepl hooks run automatically during AI-assisted edits:\n\n1. **Before edit**: Agent proposes code changes\n2. **Validate**: brepl checks syntax, auto-fixes brackets if needed\n3. **Write**: File is written with validated/corrected code\n4. **Evaluate**: brepl loads file into your running REPL (if available)\n5. **Feedback**: Agent sees warnings but continues unless syntax is invalid\n\nThis keeps your REPL state synchronized with file changes and catches errors early, without interrupting flow for recoverable issues like undefined symbols during incremental development.\n\n#### Backup \u0026 Recovery\n\nbrepl automatically creates session-specific backups before validating edits. If syntax errors are detected post-write, the original file is restored from backup. Backups are stored in `/tmp/brepl-hooks-\u003csession-id\u003e/` and cleaned up automatically.\n\n#### Project-Aware Integration\n\nHooks work with brepl's project-aware port discovery (v1.3.0+). When evaluating files, brepl walks up from the file's directory to find the correct `.nrepl-port`, so multi-project workflows just work:\n\n```bash\n# Directory structure:\n# ~/projects/\n#   ├── service-a/\n#   │   ├── .nrepl-port (7000)\n#   │   └── src/api.clj\n#   └── service-b/\n#       ├── .nrepl-port (8000)\n#       └── src/handler.clj\n\n# Each file evaluates against its own REPL\nbrepl hooks eval ~/projects/service-a/src/api.clj      # port 7000\nbrepl hooks eval ~/projects/service-b/src/handler.clj  # port 8000\n```\n\n#### Design Philosophy: Pragmatic Integration\n\nbrepl takes a pragmatic approach to AI-assisted Clojure development: use battle-tested tools when available, provide clear feedback when not.\n\n**Minimal Core with Optional Enhancement:**\n\n- ✅ Syntax validation uses edamame (built into Babashka)\n- ✅ No protocol servers or separate processes required\n\n**Direct REPL Integration:**\n\n- ✅ Uses your running nREPL connection (no separate context)\n- ✅ Works with any nREPL server (Babashka, Clojure, ClojureScript)\n- ✅ Minimal overhead (fast Babashka startup)\n- ✅ Graceful degradation (works without nREPL for syntax checking)\n- ✅ Project-aware (handles multiple REPLs automatically)\n\n**Installation Options:**\n\nPerfect for developers who want reliable AI assistance without managing multiple processes or protocol servers.\n\n## Troubleshooting\n\n**Error: No port specified, no .nrepl-port file found, and BREPL_PORT not set**\n\n- Start an nREPL server first: `bb nrepl-server`\n- Or specify port manually: `brepl -p 7888 -e \"(+ 1 2)\"`\n\n**Error connecting to nREPL server**\n\n- Check if nREPL server is running\n- Verify the port number is correct\n- For remote connections, ensure host is reachable\n\n**Get help anytime:** `brepl --help`\n\n## Requirements\n\n- [Babashka](https://babashka.org/) installed\n- Running nREPL server (Babashka, Clojure, etc.)\n\n## Development\n\n### Setup\n\n```bash\n# Enter development shell (configures git hooks automatically)\nnix-shell\n\n# Or manually configure hooks\ngit config core.hooksPath .githooks\n```\n\n### Building\n\nbrepl uses uberscript for distribution. The `brepl` file in the repo is generated from `src/`.\n\n```bash\n# Rebuild after editing source\nbb build\n\n# The pre-commit hook rebuilds automatically when src/ changes\n```\n\n### Running Tests\n\nThe project includes a comprehensive test suite. To run tests:\n\n```bash\n# Run all tests\nbb test\n\n# Run specific test namespace\nbb test --nses brepl-test\n\n# Run specific test\nbb test --vars brepl-test/basic-evaluation-test\n```\n\nThe test suite covers:\n\n- Basic expression evaluation\n- File loading and execution\n- Error handling and exceptions\n- Output handling (stdout/stderr)\n- Port and host resolution\n- Environment variable handling\n- Verbose mode functionality\n- CLI argument validation\n- Edge cases and error conditions\n\n### Verbose Mode\n\nUse `--verbose` to debug nREPL communication:\n\n```bash\nbrepl -p 1667 -e '(+ 1 2)' --verbose\n# Shows the complete nREPL message exchange:\n# {\"op\" \"eval\", \"code\" \"(+ 1 2)\", \"id\" \"1749559876543\"}\n# {\"id\" \"1749559876543\", \"ns\" \"user\", \"session\" \"none\", \"value\" \"3\"}\n# {\"id\" \"1749559876543\", \"session\" \"none\", \"status\" [\"done\"]}\n```\n\n## License\n\nMPL-2.0 License\n\n## Versioning\n\nbrepl follows [break versioning](https://www.taoensso.com/break-versioning):\n\n- Version format: `\u003cmajor\u003e.\u003cminor\u003e.\u003cnon-breaking\u003e`\n- Breaking changes increment the minor version (e.g., 1.0.0 → 1.1.0)\n- Non-breaking changes increment the patch version (e.g., 1.0.0 → 1.0.1)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\nBefore submitting a PR:\n\n1. Ensure all tests pass: `bb test`\n2. Add tests for any new functionality\n3. Update documentation as needed\n","funding_links":[],"categories":["CLI Tools"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flicht1stein%2Fbrepl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flicht1stein%2Fbrepl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flicht1stein%2Fbrepl/lists"}