Skip to content

17.LSP Configuration.md

Latest commit

 

History

History
176 lines (117 loc) · 5.4 KB

17.LSP Configuration.md

File metadata and controls

176 lines (117 loc) · 5.4 KB

Snow CLI User Guide - LSP Configuration and Usage

Welcome to Snow CLI! Agentic coding in your terminal.

What is LSP

LSP (Language Server Protocol) is a standard protocol that enables a "language server" to provide capabilities to editors/tools, such as:

  • Go to Definition
  • Document Symbols / Outline
  • Hover
  • References
  • Completion

How Snow CLI uses LSP

Snow CLI will try to use LSP first for certain code-search capabilities. If LSP is unavailable or times out, it automatically falls back to regex/text-based search (so it won’t block usage).

Currently, LSP mainly enhances these built-in tools:

  • ace-search (action=find_definition): prefers LSP "go to definition"; falls back to regex search on failure
  • ace-search (action=file_outline): prefers LSP documentSymbol; falls back to regex search on failure

Notes:

  • LSP calls have an internal timeout (default: 3 seconds). Large projects or cold-starting language servers may exceed this timeout and trigger fallback.
  • Some servers (e.g., OmniSharp) strongly depend on accurate cursor position; it’s recommended to provide contextFile + line + column when calling tools (see below).

Config file location and loading behavior

LSP config file path: ~/.snow/lsp-config.json

Loading behavior:

  1. When Snow CLI first needs LSP, it attempts to read ~/.snow/lsp-config.json.
  2. If the file does not exist, Snow CLI creates a default config file and uses the built-in default server list.
  3. The config is cached in-process; restart Snow CLI after editing the file.

Config file formats

Two formats are supported:

Format 1 (recommended): with schemaVersion

{
	"schemaVersion": 1,
	"servers": {
		"typescript": {
			"command": "typescript-language-server",
			"args": ["--stdio"],
			"fileExtensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
			"installCommand": "npm install -g typescript-language-server typescript",
			"initializationOptions": {}
		}
	}
}

Format 2 (compatible): servers mapping at the root

{
	"typescript": {
		"command": "typescript-language-server",
		"args": ["--stdio"],
		"fileExtensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]
	}
}

Configuration fields

Each language server entry supports:

  • command (required): command used to start the language server (must be resolvable from PATH)
  • args (required): argument array
  • fileExtensions (required): file extensions used to match files to this language
  • installCommand (optional): an installation hint (Snow CLI will not run it automatically)
  • initializationOptions (optional): forwarded to the LSP initialize request as initializationOptions

Important:

  • The config uses an "all-or-nothing" validation strategy: if any server entry is missing required fields or has incorrect types, the entire config is treated as invalid and Snow CLI falls back to defaults.
  • Language selection is based on file extensions (e.g., .ts, .py). Ensure your fileExtensions match your actual project files.

Default built-in servers (written on first creation)

Default language keys (you can add/remove/modify):

  • typescript: typescript-language-server --stdio
  • python: pylsp
  • go: gopls
  • rust: rust-analyzer
  • java: jdtls
  • csharp: csharp-ls

Note: installation methods differ by platform. The main requirement is that command can be found from your terminal.

Install and verify (Windows examples)

On Windows, Snow CLI uses where <command> to check whether a language server is installed and available on PATH.

You can verify manually:

where typescript-language-server
where pylsp
where gopls
where rust-analyzer
where jdtls
where csharp-ls

Common installation examples:

  1. TypeScript / JavaScript
npm install -g typescript-language-server typescript
  1. Python
python -m pip install python-lsp-server
  1. Go
go install golang.org/x/tools/gopls@latest

If you don’t want to install LSP for a language, remove its entry (or remove its extensions). Snow CLI will fall back to regex search.

Using LSP via ACE tools

1) Go to definition: ace-search (action=find_definition)

If you provide contextFile, Snow CLI will try LSP first; otherwise it uses regex search directly.

It’s recommended to pass cursor position:

  • line: 0-indexed (first line is 0)
  • column: 0-indexed (first column is 0)

Example: if your editor shows "Line 34, Column 7", you usually pass line=33, column=6.

2) File outline: ace-search (action=file_outline)

For extracting symbols from a single file, Snow CLI tries LSP documentSymbol first and falls back to regex search.

Tip:

  • For large files/projects, start with ace-search (action=file_outline) to get a high-level map, then drill down.

FAQ

1. I edited the config but nothing changed

  • Make sure ~/.snow/lsp-config.json is saved
  • Restart Snow CLI (config is cached)

2. It always falls back to regex search

Common causes:

  • Language server not installed or not on PATH (verify with where <command> on Windows)
  • fileExtensions does not match your actual file suffixes
  • Language server startup is slow and hits the 3s timeout

3. Inaccurate jumps / wrong results

  • Provide contextFile + line + column when calling ace-search (action=find_definition)
  • If symbolName appears multiple times in the file and you don’t pass position, Snow CLI will try the first occurrence, which may be inaccurate