brepl

Bracket-fixing REPL for AI-assisted Clojure development.

What is brepl?

brepl (Bracket-fixing REPL) enables AI-assisted Clojure development by solving the notorious parenthesis problem. It fully supports Claude Code and ECA (Editor Code Assistant) through their hook systems, providing three essential capabilities:

1. 🔧 Automatic bracket fixing - Intelligently corrects mismatched parentheses, brackets, and braces using parmezan
2. ⚡ Simple REPL evaluation - Gives AI agents a straightforward way to evaluate code in your running REPL, enabling truly interactive development
3. 🔄 Live file synchronization - Automatically evaluates edited files in the REPL, providing early feedback on evaluation errors before they become problems

Primary use case: Claude Code, ECA, and other AI coding agents that need reliable Clojure syntax handling and immediate REPL feedback.

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.

Bracket Auto-Fix

brepl uses parmezan for intelligent bracket correction:

• Pure Clojure: No external binary dependencies required
• Automatic fixing: Corrects mismatched delimiters, missing brackets, and extra closing parens
• Graceful fallback: Blocks with syntax errors when auto-fix is not possible

Quick Start

For AI-Assisted Development with Claude Code

Assuming brepl is already installed (see Installation):

# Start your nREPL server
bb nrepl-server

# Install hooks and skill in your project
brepl hooks install

The brepl hooks install command configures Claude Code to:

• Validate and auto-fix brackets before every file edit
• Evaluate changed Clojure files in your running REPL after edits
• Provide immediate feedback on syntax and evaluation errors
• Install the brepl skill that teaches Claude:
  • Heredoc pattern for reliable code evaluation
  • Error recovery workflows

Now Claude can write Clojure code confidently without worrying about parentheses or missing REPL feedback.

For ECA (Editor Code Assistant)

brepl fully supports ECA (GitHub), an open source editor-agnostic AI pair programming tool:

# Start your nREPL server
bb nrepl-server

# Install ECA hooks in your project
brepl eca install

The 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.

For Command-Line Usage

# Evaluate expressions (auto-detects .nrepl-port)
brepl -e '(+ 1 2 3)'
# => 6

# Load and execute files
brepl -f script.clj

# Bracket fixing is automatic in hook mode

Features

Core Capabilities for AI-Assisted Development

🔧 Bracket Fixing

• Intelligent auto-correction - Uses parmezan to fix mismatched delimiters automatically
• Pre-edit validation - Catches and fixes bracket problems before they're written to files
• Detailed error reporting - When auto-fix isn't possible, provides clear syntax errors for AI agents
• No external dependencies - Pure Clojure solution, no binary installation required

⚡ Simple REPL Evaluation

• Direct nREPL integration - AI agents can evaluate code in your running REPL with simple commands
• Heredoc pattern - Skill teaches reliable evaluation pattern that eliminates shell quoting issues
• Automatic bracket correction - Bracket errors are fixed automatically in hook mode
• Project-aware discovery - Automatically finds the right REPL for each file (v1.3.0)
• Full protocol support - Access any nREPL operation, not just evaluation
• Fast Babashka runtime - Instant startup for responsive AI interactions

🔄 Live File Synchronization

• Automatic evaluation - Files are evaluated in REPL immediately after editing
• Early error feedback - AI agents see evaluation errors right away, not later
• Session-based backups - Automatic backup/restore protects against bad edits
• One-command setup - brepl hooks install enables everything in seconds

Versatile CLI Client

• 🚀 Fast command-line evaluation - Quick one-liners with brepl -e '(+ 1 2)'
• 📁 File loading - Execute entire Clojure files with brepl -f script.clj
• 💬 Raw nREPL messages - Send any protocol message for advanced operations
• 🔍 Smart port discovery - Automatically detects .nrepl-port files
• ⚙️ Flexible configuration - Environment variables and CLI arguments
• 🐛 Proper error handling - Shows exceptions and stack traces
• 📊 Verbose mode - Debug nREPL communication with --verbose

Installation

Option 1: Install via bbin (recommended)

bbin install io.github.licht1stein/brepl

Option 2: Direct download (curl)

curl -fsSL https://raw.githubusercontent.com/licht1stein/brepl/master/brepl -o ~/.local/bin/brepl
chmod +x ~/.local/bin/brepl

Option 3: Install with Nix

{ pkgs ? import <nixpkgs> {} }:

let
  brepl = pkgs.callPackage (pkgs.fetchFromGitHub {
    owner = "licht1stein";
    repo = "brepl";
    rev = "v2.7.1";
    hash = "sha256-Obv2kSEsgZacY4T3HU1/FqTx4y2dRiCgk9j2tPPd3+o=";
  } + "/package.nix") {};
in
pkgs.mkShell {
  buildInputs = [ brepl ];
}

Then run nix-shell to enter a shell with brepl available.

Option 4: Manual Installation

git clone https://github.com/licht1stein/brepl.git
cd brepl

# Add to PATH
ln -s $(pwd)/brepl ~/.local/bin/brepl

Usage

Get help: brepl --help

Command Line Options

  -e, --e          <expr>     Expression to evaluate
  -f, --f          <file>     File to load and execute
  -m, --m, --message <message> Raw nREPL message (EDN format)
  -h, --h          <host>     nREPL host (default: localhost or BREPL_HOST)
  -p, --p          <port>     nREPL port (required - auto-detects from .nrepl-port or BREPL_PORT)
      --verbose              Show raw nREPL messages instead of parsed output
      --version              Show brepl version
  -?, --help                 Show help message

Hook Subcommands

brepl hooks install              # Install hooks to .claude/settings.local.json (includes skill)
brepl hooks uninstall            # Remove hooks
brepl hooks validate <file> <content>  # Pre-edit validation with auto-fix
brepl hooks eval <file>          # Post-edit evaluation
brepl hooks stop                 # Run stop hooks from .brepl/hooks.edn
brepl hooks session-end          # Cleanup session backups (reads JSON from stdin)

Note: hook works as an alias for hooks for backward compatibility.

Skill Commands

brepl skill install             # Install brepl skill to .claude/skills/brepl
brepl skill uninstall           # Remove brepl skill

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.

What the skill teaches Claude:

• Heredoc pattern for reliable code evaluation
• In-place file fixing workflows
• Error recovery patterns

Examples:

# Fix brackets in an expression
# => (defn foo [])

# Fix brackets in a file

Basic Usage

# Evaluate an expression (auto-detects port from .nrepl-port)
brepl -e '(+ 1 2 3)'

# Load and execute a file
brepl -f script.clj

# Use single quotes to avoid escaping double quotes
brepl -e '(println "Hello, World!")'

Heredoc Pattern for Reliable Evaluation

For 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:

# Standard heredoc pattern - works for all cases
brepl <<'EOF'
(require '[clojure.string :as str])
(str/join ", " ["a" "b" "c"])
EOF

Why use heredoc?

• No quoting issues: Everything between <<'EOF' and EOF is treated as literal input
• Consistent pattern: One approach for all evaluations, from simple to complex
• Multi-line friendly: Natural formatting for readable code
• Easy to extend: Add more forms without changing syntax

Examples:

# Multi-line expressions with complex quoting
brepl <<'EOF'
(println "String with 'single' and \"double\" quotes")
(+ 10 20)
EOF

# Namespace reloading and testing
brepl <<'EOF'
(require '[myapp.core] :reload)
(myapp.core/some-function "test" 123)
EOF

# Data structures with nested quotes
brepl <<'EOF'
(def config
  {:database {:host "localhost"
              :port 5432}
   :api {:key "secret-key"}})
(println (:database config))
EOF

Note: Always use <<'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.

Port Configuration

The port is resolved in this order:

1. Command line: -p 7888
2. Auto-detect: .nrepl-port file
   • For -f flag: searches from the file's directory upward (v1.3.0+)
   • For -e/-m flags: uses current directory
3. Environment: BREPL_PORT=7888
4. Process scanning: discovers running nREPL servers automatically (see below)

# Explicit port
brepl -p 7888 -e '(+ 1 2)'

# Using environment variable
BREPL_PORT=7888 brepl -e '(+