diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index bd9cb0f..06bfef7 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -183,6 +183,22 @@ make test-basic
 make test-config
 ```
 
+### Running Tests from Within Neovim/Claude Code
+
+When running tests from within a Neovim instance (such as when using Claude Code via claude-code.nvim), the test script automatically handles the `$NVIM` environment variable which normally points to a socket file instead of the nvim executable.
+
+The test script will:
+
+- Use the `$NVIM` variable if it points to a valid executable file
+- Fall back to finding `nvim` in `$PATH` if `$NVIM` points to a socket or invalid path
+- Display which nvim binary is being used for transparency
+
+To verify the NVIM detection logic works correctly, you can run:
+
+```bash
+./scripts/test_nvim_detection.sh
+```
+
 ### Writing Tests
 
 Tests are written in Lua using a simple BDD-style API:
diff --git a/scripts/test.sh b/scripts/test.sh
index 529dd6a..ab2b348 100755
--- a/scripts/test.sh
+++ b/scripts/test.sh
@@ -12,12 +12,16 @@ cd "$PLUGIN_DIR"
 # Print current directory for debugging
 echo "Running tests from: $(pwd)"
 
-# Find nvim 
-NVIM=${NVIM:-$(which nvim)}
-
-if [ -z "$NVIM" ]; then
-  echo "Error: nvim not found in PATH"
-  exit 1
+# Find nvim - ignore NVIM env var if it points to a socket
+if [ -n "$NVIM" ] && [ -x "$NVIM" ] && [ ! -S "$NVIM" ]; then
+  # NVIM is set and is an executable file (not a socket)
+  echo "Using NVIM from environment: $NVIM"
+else
+  # Find nvim in PATH
+  if ! NVIM=$(command -v nvim); then
+    echo "Error: nvim not found in PATH"
+    exit 1
+  fi
 fi
 
 echo "Running tests with $NVIM"
diff --git a/scripts/test_nvim_detection.sh b/scripts/test_nvim_detection.sh
new file mode 100755
index 0000000..5f52349
--- /dev/null
+++ b/scripts/test_nvim_detection.sh
@@ -0,0 +1,65 @@
+#!/bin/bash
+set -euo pipefail
+
+# Test script to verify NVIM environment variable detection logic
+# This script tests the fix for handling NVIM variable when running inside Neovim
+
+# Get the absolute directory path of this script
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+echo "Testing NVIM environment variable detection..."
+
+# Save original NVIM value
+ORIGINAL_NVIM="$NVIM"
+
+# Test 1: NVIM points to a socket (simulating inside Neovim)
+echo "Test 1: NVIM points to a socket"
+export NVIM="/tmp/test_socket"
+mkfifo "$NVIM" 2>/dev/null || true  # Create a named pipe (similar to socket)
+if timeout 5 bash -c "cd '$PROJECT_DIR' && ./scripts/test.sh" 2>&1 | head -10 | grep -q "Running tests with.*nvim"; then
+    echo "✓ Fallback to PATH works"
+else
+    echo "✗ Fallback failed"
+fi
+rm -f "$NVIM"
+
+# Test 2: NVIM points to valid executable
+echo "Test 2: NVIM points to valid executable"
+if ! NVIM=$(command -v nvim); then
+  echo "Error: nvim not found in PATH"
+  exit 1
+fi
+export NVIM
+if timeout 5 bash -c "cd '$PROJECT_DIR' && ./scripts/test.sh" 2>&1 | head -10 | grep -q "Using NVIM from environment"; then
+    echo "✓ Using provided NVIM works"
+else
+    echo "✗ Using provided NVIM failed"
+fi
+
+# Test 3: NVIM points to non-existent path
+echo "Test 3: NVIM points to non-existent path"
+export NVIM="/nonexistent/nvim"
+if timeout 5 bash -c "cd '$PROJECT_DIR' && ./scripts/test.sh" 2>&1 | head -10 | grep -q "Running tests with.*nvim"; then
+    echo "✓ Fallback from invalid path works"
+else
+    echo "✗ Fallback from invalid path failed"
+fi
+
+# Test 4: NVIM is unset
+echo "Test 4: NVIM is unset"
+unset NVIM
+if timeout 5 bash -c "cd '$PROJECT_DIR' && ./scripts/test.sh" 2>&1 | head -10 | grep -q "Running tests with.*nvim"; then
+    echo "✓ Unset NVIM works"
+else
+    echo "✗ Unset NVIM failed"
+fi
+
+# Restore original NVIM value
+if [ -n "$ORIGINAL_NVIM" ]; then
+  export NVIM="$ORIGINAL_NVIM"
+else
+  unset NVIM
+fi
+
+echo "All NVIM detection tests completed!"
\ No newline at end of file