ashaykubal/setup-lsp

Setup LSP

Configure Language Server Protocol integration for Claude Code projects. LSP replaces text-based grep/glob searches with semantic code intelligence: go-to-definition, find-references, hover type info, call hierarchy, and real-time error detection.

---

Mandatory Execution Checklist (BINDING)

Every applicable item below is mandatory. No deviations. No substitutions. No skipping.

This skill uses a 9-stage pipeline. You are the orchestrator. Follow every item in order. Do NOT return to the user until all applicable items are checked.

• [ ] Stage 1 — Parse: Arguments read, MODE determined (full | verify | troubleshoot), --lang extracted if present
• [ ] Stage 2 — Detect: references/server-registry.md loaded, manifest files scanned, DETECTED_LANGUAGES presented to user
• [ ] Stage 3 — Binaries: Binary install command run for each confirmed language
• [ ] Stage 4 — Settings: ENABLE_LSP_TOOL=1 set in ~/.claude/settings.json and shell profile
• [ ] Stage 5 — Guide Plugin Install: Present user with exact plugin names and instructions to install via /plugin or CLI
• [ ] Stage 6 — Checkpoint: Session ID captured via ${CLAUDE_SESSION_ID}, exact claude --resume command presented to user, execution STOPPED
• [ ] Stage 7 — Verify: (on --verify) Debug log read, Total LSP servers loaded: N checked
• [ ] Stage 8 — Diagnostics: (if verification failed or --troubleshoot) references/troubleshooting.md loaded, issues checked in order
• [ ] Stage 9 — Report: templates/diagnostic-output.yaml loaded, diagnostic YAML written to logs/diagnostics/, summary presented to user

Do NOT declare complete until all applicable checkboxes are marked.

---

When to Use This Skill

| Trigger Pattern | Scenario | Mode | |-----------------|----------|------| | Starting LSP setup from scratch | Project has no LSP configured | Full setup (no flags) | | After restarting Claude Code following plugin install | Session resumed, verifying LSP loaded | --verify | | LSP tools not appearing or servers not responding | Debugging a broken LSP configuration | --troubleshoot |

DO NOT use for:

• Projects where LSP is already confirmed working (check ~/.claude/debug/latest first)
• Adding new language support to an already-configured LSP environment (run full setup again)

---

Pre-Flight Gate (BINDING)

STOP. Before running any installation steps, check the invocation flag.

IF $ARGUMENTS contains "--verify":
    SKIP to Stage 7 (Verify Initialization)
IF $ARGUMENTS contains "--troubleshoot":
    SKIP to Stage 8 (Diagnostics)
IF $ARGUMENTS contains "--lang":
    Extract comma-separated language names → EXPLICIT_LANGUAGES
    Execute ALL stages in order, but Stage 2 uses EXPLICIT_LANGUAGES instead of scanning
OTHERWISE:
    Execute ALL stages in order (Stage 1 through Stage 9)

You MUST NOT skip stages or reorder them during full setup.

---

Dependencies

| File | Requirement | When to Load | |------|-------------|--------------| | references/server-registry.md | REQUIRED | Stage 2 (detection) and Stage 3 (install) | | references/troubleshooting.md | REQUIRED | Stage 8 (diagnostics) and whenever verification fails | | templates/diagnostic-output.yaml | REQUIRED | Stage 9 (report results) |

Read each file at the stage where it is first needed. Do not defer loading.

---

Usage

/setup-lsp                          Full setup: detect → install binaries → guide plugin install → checkpoint → verify
/setup-lsp --lang typescript,python Skip detection, install specified languages directly
/setup-lsp --verify                 Post-restart verification only (skip installation)
/setup-lsp --troubleshoot           Diagnostics only (no installation)

---

Workflow

Stage 1: Parse Arguments

Read $ARGUMENTS. Determine MODE (full | verify | troubleshoot) per Pre-Flight Gate above. If --lang is present, extract the comma-separated language names into EXPLICIT_LANGUAGES (e.g., --lang typescript,python → ["typescript", "python"]). Report mode (and explicit languages if any) to user before proceeding.

---

Stage 2: Detect Tech Stack

Read references/server-registry.md.

If EXPLICIT_LANGUAGES was set in Stage 1 (via --lang): Look up each language name in the server registry. Build DETECTED_LANGUAGES from the matching entries (use "user-specified" as manifest path). If any language name doesn't match the registry, report the mismatch and ask user to clarify.

Otherwise: Scan project root and up to 2 directory levels deep for manifest files listed in the Official LSP Plugins table. For monorepos, scan each subdirectory independently. See registry for monorepo scanning guidance. Build DETECTED_LANGUAGES list (language, manifest path, plugin name).

If DETECTED_LANGUAGES is empty (no manifest files found):

No supported languages detected in this project.

You can select languages manually from the server registry:
  1. TypeScript/JavaScript
  2. Python
  3. Go
  4. Rust
  5. Java
  6. C#
  7. PHP
  8. C/C++
  9. Kotlin
  10. Swift
  11. Lua
  (See references/server-registry.md for full list)

Select languages to set up (comma-separated numbers), or 'skip' to abort:

Use AskUserQuestion to present the language list. If user selects 'skip', report "No languages selected" and proceed directly to Stage 9 (Report Results).

If DETECTED_LANGUAGES is non-empty, present to user:

Detected languages:
  - {language} ({manifest path}) → plugin: {plugin-name}

Proceed with installation? (yes / adjust)

Wait for user confirmation before continuing to Stage 3.

---

Stage 3: Install Language Server Binaries

Read references/server-registry.md. Use the binary install commands for each confirmed language.

For each language in DETECTED_LANGUAGES:

1. Run the binary install command from the registry
2. Verify the binary is available: which {binary-name}
3. Report success or failure per language

If any binary install fails: report the error, note the language as FAILED, continue with remaining languages.

---

Stage 4: Configure Settings

Step 4a — Set ENABLE_LSP_TOOL in settings.json:

Read ~/.claude/settings.json. Add "ENABLE_LSP_TOOL": "1" if not already present. Write back.

Step 4b — Set ENABLE_LSP_TOOL in shell profile:

Check which shell profile exists (~/.bashrc or ~/.zshrc). Add export ENABLE_LSP_TOOL=1 if not already present.

Note: ENABLE_LSP_TOOL is an undocumented flag required for LSP tool activation (community report #15619).

---

Stage 5: Guide User Through Plugin Installation (BLOCKING — User Action Required)

IMPORTANT: Claude CANNOT run claude plugin install or claude plugin enable commands from within a session. These must be performed by the user.

Step 5a — Ask about installation scope:

Use AskUserQuestion to ask the user which scope to install plugins in:

Which scope should the LSP plugins be installed in?

1. User scope (default) — available across all your projects (~/.claude/settings.json)
2. Project scope — shared with team via version control (.claude/settings.json)
3. Local scope — project-specific, gitignored (.claude/settings.local.json)

Record the chosen scope. For Option B CLI instructions, map to: --scope user, --scope project, or --scope local.

Step 5b — Present plugin installation instructions and ask for status:

First, present the installation instructions as plain text output (NOT inside AskUserQuestion):

PLUGIN INSTALLATION — USER ACTION REQUIRED

The language server binaries are installed. Now you need to install the
Claude Code LSP plugins for each language.

Scope: {chosen scope} ({scope description})

Option A — Using /plugin (within this session):
  1. Type /plugin
  2. Go to the "Discover" tab
  3. Search for and install each plugin:
{for each language in DETECTED_LANGUAGES}
     - {plugin-name}
{end}
  4. When prompted for scope, select "{scope label}" to match your
     earlier choice. The options shown will be:
       - "Install for you (user scope)"
       - "Install for all collaborators on this repository (project scope)"
       - "Install for you, in this repo only (local scope)"
     Select the one matching: {chosen scope}.

Option B — Using CLI (from a separate terminal):
  claude plugin marketplace update claude-plugins-official
{for each language in DETECTED_LANGUAGES}
  claude plugin install {plugin-name} --scope {chosen-scope}
{end}

Then use AskUserQuestion with two options:

1. "I've installed them" — plugins are already installed, proceed to next step
2. "I'll install them in this session" — dismiss this prompt so I can use /plugin

If user selects option 1: Proceed to Stage 6 (Checkpoint).

If user selects option 2: Dismiss the question and present this note as plain text:

No problem. Install the plugins using /plugin or from a separate terminal.

Once installation is complete, confirm here and I'll continue with the
remaining setup (exit+resume for LSP initialization).

Then WAIT for the user's natural text confirmation before proceeding to Stage 6. Do NOT present another AskUserQuestion — let the user type freely so they can use /plugin and other commands.

---

Stage 6: Exit and Resume Checkpoint (BLOCKING)

LSP servers only initialize at startup. This stage is mandatory and non-skippable.

The current session ID is available as ${CLAUDE_SESSION_ID}. Present to user and STOP:

LSP SETUP REQUIRES EXIT AND RESUME

Exit Claude Code now, then resume this session:

    claude --resume ${CLAUDE_SESSION_ID}

After resuming, run /setup-lsp --verify to confirm servers loaded.

Do NOT continue past this stage. Execution resumes only when user invokes --verify in the resumed session.

---

Stage 7: Verify Initialization

This stage runs on --verify invocation after session resume.

Read ~/.claude/debug/latest (internal debug log, path may change in future versions). Search for Total LSP servers loaded: N.

• N > 0 → PASSED. Note which servers appear.
• N = 0 → FAILED. Proceed to Stage 8.
• Line absent → Log not yet updated. Ask user to wait 10 seconds and retry.

Also check the /plugin Errors tab output if available — Executable not found in $PATH indicates a binary installation issue (see troubleshooting issue #5).

---

Stage 8: Diagnostics

Read references/troubleshooting.md. Work through the 5 common issues in order: run each detection method, apply fix if detected, report result. After applying fixes, re-run verification (Stage 7) and report outcome.

---

Stage 9: Report Results

Read templates/diagnostic-output.yaml. Fill all fields. Write completed diagnostic to logs/diagnostics/lsp-setup-{YYYYMMDD-HHMMSS}.yaml.

Present summary:

LSP Setup Complete

Detected languages:   {list}
Installed binaries:   {list with status: ok | failed}
Plugins installed:    {list — user-confirmed}
Verification status:  PASSED | FAILED | PENDING (awaiting resume)
Issues found:         {count} ({list if any})
Session ID:           {SESSION_ID}
Diagnostic log:       ./logs/diagnostics/lsp-setup-{timestamp}.yaml

If any server failed or verification failed, include next steps from references/troubleshooting.md.

If plugins were installed for languages without matching source files in the project (e.g., rust-analyzer-lsp installed but no .rs files or Cargo.toml present), append this note:

Note: Some LSP servers may show startup errors if there are no matching
source files in this project yet. This is expected — the server starts
but cannot find a workspace to index. Once you add source files for that
language (e.g., create a Cargo.toml for Rust), the server will activate
automatically on next session start.