bash-lsp-plugin

bash-lsp-plugin

A Claude Code plugin that provides Language Server Protocol (LSP) support for Bash/Shell scripts using bash-language-server.

Quick Start

Get started in 3 steps:

# 1. Install dependencies
npm install -g bash-language-server
brew install shellcheck  # or apt/pacman install shellcheck

# 2. Load the plugin with Claude Code
claude --plugin-dir /path/to/bash-lsp-plugin

# 3. Open a bash script
# LSP will automatically provide diagnostics and code intelligence

See Prerequisites for alternative installation methods.

Features

The bash-language-server provides intelligent code assistance for Bash scripts:

• Syntax Validation - Real-time detection of syntax errors
• Code Completion - Suggestions for commands, variables, and functions
• Function Navigation - Jump to function definitions
• Variable Tracking - Detection of undefined or unused variables
• ShellCheck Integration - Linting and best practice suggestions
• Hover Documentation - Inline documentation for commands
• Code Formatting - Automatic script formatting
• Symbol Search - Find functions and variables across files

Supported File Extensions

• .sh - Shell scripts

Prerequisites

This plugin requires two dependencies:

1. bash-language-server (required) - Provides LSP functionality
2. ShellCheck (recommended) - Provides linting and best practices

bash-language-server Installation

Via npm (recommended)

npm install -g bash-language-server

Via Homebrew (macOS)

brew install bash-language-server

Via package manager (Linux)

Ubuntu/Debian:

sudo apt install node-bash-language-server

Arch Linux:

sudo pacman -S bash-language-server

Verify bash-language-server Installation

bash-language-server --version

Expected output: 5.6.0 (or newer)

ShellCheck Installation (Recommended)

ShellCheck provides linting and best practice suggestions. While optional, it's highly recommended for full functionality.

macOS:

brew install shellcheck

Ubuntu/Debian:

sudo apt install shellcheck

Arch Linux:

sudo pacman -S shellcheck

Or download from: https://github.com/koalaman/shellcheck/releases

Verify installation:

shellcheck --version

Expected output: ShellCheck - shell script analysis tool, version: 0.10.0 (or newer)

Plugin Structure

bash-lsp-plugin/
├── plugin.json              # Plugin metadata
├── .lsp.json               # LSP server configuration
├── .shellcheckrc           # ShellCheck style configuration (optional)
├── .claude/
│   └── settings.local.json # Permission settings
├── README.md               # This file
├── CONFIGURATION.md        # Style and configuration guide
└── TROUBLESHOOTING.md      # Debug and troubleshooting guide

Custom Style Configuration

This plugin includes a custom .shellcheckrc configuration with enhanced optional checks:

• require-variable-braces - Enforces ${var} syntax for consistency
• deprecate-which - Suggests command -v instead of which
• avoid-nullary-conditions - Requires explicit -n in conditionals
• add-default-case - Ensures case statements have *) default
• check-unassigned-uppercase - Catches typos in uppercase variables

See CONFIGURATION.md for details on customizing ShellCheck behavior.

Configuration Files

plugin.json - Basic plugin information:

{
  "name": "bash-lsp-plugin",
  "description": "An LSP plugin using bash-lsp/bash-language-server",
  "version": "1.0.0",
  "author": {
    "name": "arbal"
  }
}

.lsp.json - LSP server configuration:

{
  "bash": {
    "command": "bash-language-server",
    "args": ["start"],
    "extensionToLanguage": {
      ".sh": "bash"
    }
  }
}

.claude/settings.local.json - Permissions:

{
  "permissions": {
    "allow": [
      "Bash(bash-language-server:*)"
    ]
  }
}

Testing

The plugin includes comprehensive test files to verify LSP functionality:

• test.sh - Comprehensive test covering all major bash features
• test-errors.sh - Intentional syntax errors to test error detection
• test-advanced.sh - Advanced bash features and edge cases

Running Tests

1. Open any .sh file in Claude Code
2. The LSP should automatically start and provide diagnostics
3. Look for real-time syntax checking, completions, and suggestions

Expected LSP Diagnostics

When working with the test files, you should see:

• ✅ Unused variable warnings (shellcheck SC2034)
• ✅ Suggestions for modern syntax (shellcheck SC2006, SC2219)
• ✅ Best practice recommendations (shellcheck SC2012)
• ✅ Syntax error detection in test-errors.sh

Usage

Once the plugin is loaded in Claude Code: