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

# Or add the marketplace and install it
claude plugins marketplace add /path/to/bash-lsp-plugin
claude plugins install bash-lsp-plugin@bash-lsp-plugin-marketplace

# 3. Open a bash script
# LSP will provide diagnostics and navigation; formatting is available when the client requests it

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 - shfmt support when the LSP client requests document formatting
• Symbol Search - Find functions and variables across files

Supported File Extensions

• .sh - Shell scripts
• .bash - Bash scripts Files with zsh or ksh extensions are intentionally not claimed here, and hidden Bash startup files or .command files are not advertised in this release because Claude Code did not route them consistently in live tests.

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
├── .claude-plugin/
│   └── marketplace.json     # Marketplace catalog
├── .lsp.json               # LSP server configuration
├── .shellcheckrc           # ShellCheck style configuration (optional)
├── .claude/
│   └── settings.local.json # Permission settings
├── scripts/
│   └── validate.sh         # Local validation entry point
├── README.md               # This file
├── CONFIGURATION.md        # Style and configuration guide
├── RELEASING.md            # Release workflow and approval gate
└── 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",
  "displayName": "Bash LSP Plugin",
  "description": "Claude Code Bash/Shell LSP integration with ShellCheck linting and shfmt formatting",
  "version": "1.1.0",
  "author": {
    "name": "arbal"
  }
}