scala-lsp

Documentation

# Scala Metals LSP for Claude Code

A Claude Code plugin that integrates [Metals](https://scalameta.org/metals/), the Scala Language Server.

## Features

- Code completions
- Go to definition / references
- Hover documentation
- Diagnostics (errors/warnings)
- Code formatting (via Scalafmt)
- Supports `.scala`, `.sc`, and `.sbt` files

## Prerequisites

**Java 11 or later** is required. Install via one of:

- **SDKMAN** (recommended): `sdk install java 17.0.8-zulu`
- **Homebrew**: `brew install openjdk@17`
- **Nix**: `nix-env -iA nixpkgs.jdk17`
- **asdf**: `asdf plugin add java && asdf install java openjdk-17`
- **jabba**: `jabba install openjdk@17`

## Installation

### 1. Install Metals

#### Via Coursier (Recommended)

```bash
# Install Coursier if needed
brew install coursier/formulas/coursier  # macOS
# or: curl -fL https://github.com/coursier/coursier/releases/latest/download/cs-x86_64-pc-linux.gz | gzip -d > cs && chmod +x cs && ./cs setup

# Install Metals
cs install metals

# Verify
metals --version
```

#### Via Nix

```bash
nix-env -iA nixpkgs.metals
```

### 2. Install the Plugin

Add to your `~/.claude/settings.json`:

```json
{
  "enabledPlugins": {
    "/path/to/scala-lsp": true
  }
}
```

Or clone and add:

```bash
git clone https://github.com/Veske/scala-lsp.git ~/.claude/plugins/scala-lsp
```

Then add `"~/.claude/plugins/scala-lsp": true` to `enabledPlugins`.

### 3. Restart Claude Code

The LSP will auto-connect when you open Scala files.

## How It Works

The `metals-launcher` script automatically discovers:
- **Java**: SDKMAN, jabba, asdf, Homebrew, Nix, macOS `java_home`, system PATH
- **Metals**: Coursier bin directory, Nix profile, system PATH

## Troubleshooting

### "Java not found" error

Ensure Java 11+ is available:
```bash
java -version
```

If using a version manager, ensure it's initialized in your shell profile.

### Metals not in PATH

If installed via Coursier, add to your shell profile:
```bash
export PATH="$PATH:$HOME/.local/share/coursier/bin"
# or on macOS:
export PATH="$PATH:$HOME/Library/Application Support/Coursier/bin"
```

### Build server issues

Metals works best with a build tool. Ensure your project has one of:
- `build.sbt` (sbt)
- `build.sc` (Mill)
- `pom.xml` (Maven)

## Resources

- [Metals Documentation](https://scalameta.org/metals/)
- [Metals GitHub](https://github.com/scalameta/metals)
- [Coursier](https://get-coursier.io/)

## License

Apache-2.0
Keywords

Documentation
