Skip to content
Back to search

agent-lsp

MCP server that orchestrates language servers into agent-native workflows. 65 tools, 30 CI-verified languages.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/blackwell-systems/agent-lsp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/blackwell-systems/agent-lsp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/blackwell-systems--agent-lsp/badge.svg)](/listings/blackwell-systems--agent-lsp)

HTML

<a href="/listings/blackwell-systems--agent-lsp"><img src="/api/listings/blackwell-systems--agent-lsp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Step 1: Install agent-lsp

curl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh

<details> <summary>Alternative install methods</summary>

**macOS / Linux**

brew install blackwell-systems/tap/agent-lsp

**Windows**

# PowerShell (no admin required)
iwr -useb https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.ps1 | iex

# Scoop
scoop bucket add blackwell-systems https://github.com/blackwell-systems/agent-lsp
scoop install blackwell-systems/agent-lsp

# Winget
winget install BlackwellSystems.agent-lsp

**All platforms**

# pip
pip install agent-lsp

# npm
npm install -g @blackwell-systems/agent-lsp

# Go install
go install github.com/blackwell-systems/agent-lsp/cmd/agent-lsp@latest

</details>

Step 2: Install language servers

Install the servers for your stack. Common ones:

| Language | Server | Install | |----------|--------|---------| | TypeScript / JavaScript | `typescript-language-server` | `npm i -g typescript-language-server typescript` | | Python | `pyright-langserver` | `npm i -g pyright` | | Go | `gopls` | `go install golang.org/x/tools/gopls@latest` | | Rust | `rust-analyzer` | `rustup component add rust-analyzer` | | C / C++ | `clangd` | `apt install clangd` / `brew install llvm` | | Ruby | `solargraph` | `gem install solargraph` |

Full list of 32 supported languages in [docs/reference/language-support.md](./docs/reference/language-support.md).

Step 3: Verify setup

agent-lsp doctor

Probes each configured language server and reports capabilities. Fix any failures before proceeding. See [language support](./docs/reference/language-support.md) for install commands and server-specific notes.

Step 4: Configure your AI tool

agent-lsp init

Detects language servers on your PATH, asks which AI tool you use, writes the correct MCP config, and installs skill awareness rules for your AI provider (CLAUDE.md for Claude Code, `.cursor/rules/` for Cursor, `.clinerules` for Cline, `.windsurfrules` for Windsurf, `GEMINI.md` for Gemini CLI, `AGENTS.md` for Pi). For CI or scripted use: `agent-lsp init --non-interactive`.

For [Pi](https://github.com/earendil-works/pi), choose the project (`9`) or global (`10`) target. Pi has no built-in MCP support; `init` writes the shared standard MCP files that the [`pi-mcp-adapter`](https://www.npmjs.com/package/pi-mcp-adapter) package reads — project `.mcp.json` (same file Claude Code uses, so one config serves both) or global `~/.config/mcp/mcp.json`. Skill awareness rules go into `AGENTS.md` (project) or `~/.pi/agent/AGENTS.md` (global). Install the adapter once with `pi install npm:pi-mcp-adapter`.

One-command complete setup

Add `--with-skills` to also install the embedded skill files (no repo clone needed):

agent-lsp init --with-skills

Skills are written to the destination matching the chosen target: only the Pi project target (`9`) uses the tool-agnostic `.agents/skills/` directory (versionable with the repo); the Pi global target (`10`) uses `~/.pi/agent/skills/`; the Claude Code targets (`1`/`2`) use `~/.claude/skills/`; Cursor (`4`) uses `~/.cursor/skills/`; and Gemini CLI (`7`) uses `~/.config/gemini-cli/skills/`. Providers without a verified skills directory are skipped with a pointer to `skills/install.sh --dest`. Re-running overwrites the managed skill files, keeping them in sync with the installed binary. `agent-lsp uninstall` removes them.

The generated config looks like:

{
  "mcpServers": {
    "lsp": {
      "type": "stdio",
      "command": "agent-lsp",
      "args": [
        "go:gopls",
        "typescript:typescript-language-server,--stdio",
        "python:pyright-langserver,--stdio"
      ]
    }
  }
}

Each arg is `language:server-binary` (comma-separate server args).

Step 5: Install skills

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 526 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. **English** · [简体中文](docs/i18n/README.zh-CN.md) · [Русский](docs/i18n/README.ru.md) · [हिन्दी](docs/i18n/README.hi.md) · [العربية](docs/i18n/README.ar.md)
  2. <p align="center">
  3. <img src="assets/banner.png" alt="agent-lsp" width="820">
  4. </p>
  5. <p align="center">
  6. <a href="#tools"><img src="https://img.shields.io/badge/CI--verified_tools-66%2F66-brightgreen.svg" alt="CI Coverage"></a>
  7. <a href="#multi-language-support"><img src="https://img.shields.io/badge/languages-32_CI--verified-brightgreen.svg" alt="Languages"></a>
  8. <a href="https://github.com/blackwell-systems/mcp-assert"><img src="https://raw.githubusercontent.com/blackwell-systems/mcp-assert/main/assets/badge-passing.svg?v=3" alt="mcp-assert: passing" height="20"></a>
  9. <a href="https://agentskills.io"><img src="assets/badge-agentskills.svg" alt="Agent Skills"></a>
  10. <a href="https://github.com/blackwell-systems/agent-lsp"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/blackwell-systems/agent-lsp/badges/assets/downloads-badge.json" alt="downloads"></a>
  11. <br>
  12. <a href="https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/"><img src="https://img.shields.io/badge/LSP-3.17-blue.svg" alt="LSP 3.17"></a>
  13. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
  14. <a href="https://github.com/punkpeye/awesome-mcp-servers"><img src="https://img.shields.io/badge/Awesome-MCP%20Servers-fc60a8" alt="Awesome MCP Servers"></a>
  15. <a href="https://github.com/blackwell-systems"><img src="https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg" alt="Blackwell Systems"></a>
  16. </p>
  17. **Code intelligence infrastructure for AI agents.** 66 tools, 32 CI-verified languages, 24 agent workflows. Single Go binary.
  18. ```bash
  19. curl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh && agent-lsp init
  20. ```
  21. ## What is it?
  22. agent-lsp is an **MCP server** that orchestrates existing LSP servers (gopls, rust-analyzer, jdtls, etc.) into agent-native workflows.
  23. **Not an LSP server** — it's an orchestration layer that manages language servers and exposes batch operations, speculative editing, and multi-step workflows via MCP tools.
  24. **Architecture:**
  25. - **Language servers** (gopls, rust-analyzer, etc.) → provide code intelligence
  26. - **agent-lsp** (MCP server) → orchestrates workflows, maintains warm runtime
  27. - **AI agents** → consume via MCP protocol
  28. ## Why agent-lsp?
  29. **Persistent warm runtime**
  30. Language servers stay indexed across agent sessions. First session: indexes workspace (~10s for typical projects). Subsequent sessions: instant. No cold-start penalty on each request.
  31. **Batch operations**
  32. `blast_radius` → one call returns all exports + all callers (test vs non-test partitioned). Without orchestration: 20+ sequential LSP calls.
  33. **Speculative editing**
  34. `simulate_edit` → preview changes in memory, check diagnostic delta, apply or discard. Test edits before touching disk. `safe_apply_edit` writes only an edit it could verify: if the preview timed out or the server was still indexing, nothing is written.
  35. **Workflow orchestration**
  36. 24 skills that chain LSP operations into complete pipelines:
  37. - `/lsp-refactor` → impact analysis → preview → apply → verify build → run tests
  38. - `/lsp-safe-edit` → preview → diagnostic diff → apply if safe
  39. - `/lsp-verify` → LSP diagnostics → build → test suite
  40. **Multi-language, single session**
  41. One agent-lsp process routes `.go` to gopls, `.ts` to tsserver, `.py` to pyright. No reconfiguration between projects. Session persists across files and repositories. Workspace-wide queries (`find_symbol`, `get_server_capabilities`) ask every running language server, not just the default one. `start_lsp` can also `connect` to a language server that is already running (e.g. `gopls -listen`) and reuse its warm index.
  42. > [!TIP]
  43. > **Token-optimized output:** Tool responses encoded in [GCF](https://gcformat.com) instead of JSON. 30-84% fewer tokens depending on tool (up to 92.7% with session dedup). [100% LLM comprehension on every frontier model](https://gcformat.com/guide/benchmarks.html), 91.2% on complex code graphs where JSON averages 54.1%. See [below](#token-optimized-output-gcf) for measured savings per tool.
  44. **How the pieces fit together:** [LSP](https://microsoft.github.io/language-server-protocol/) (Language Server Protocol) is how editors get code intelligence: completions, diagnostics, go-to-definition. [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) is the standard way AI tools like Claude Code discover and call external tools. agent-lsp bridges the two: language server intelligence, accessible to AI agents.
  45. ## Use it when
  46. - Building agentic code generation systems
  47. - Automating refactors across large codebases
  48. - CI tooling that needs programmatic code intelligence
  49. - Any workflow where sequential LSP calls are too slow or complex
  50. ### What agents say
  51. We asked AI agents to evaluate agent-lsp across 10 coding tasks (find callers, rename safely, preview edits, detect dead code) and write an honest assessment. Four different models, four independent evaluations, same conclusion:
  52. > **Claude (Opus 4.6):** "I would recommend agent-lsp for any workflow involving refactoring, impact analysis, or safe editing. The standout tools are `blast_radius` (blast radius in one call, with test/non-test partitioning that would take 5-10 grep commands to replicate), `go_to_implementation` (type-checked interface satisfaction that grep simply cannot do), and the simulation session workflow (speculative type-checking without touching disk, which has no grep/read equivalent at all)."
  53. > **Cursor (auto):** "I would recommend agent-lsp for heavy refactors and code navigation because the rename, references, implementations, call hierarchy, and simulation tools remove a lot of brittle grep/manual-edit work and make changes safer."
  54. > **GPT-5.5 (via Codex):** "I would recommend agent-lsp for symbol-aware work: references, implementations, rename previews, diagnostics, and large-file structure are materially faster and less error-prone than grep/read loops."
  55. > **Gemini 2.5 Pro (via Gemini CLI):** "I would highly recommend agent-lsp because it provides a level of semantic awareness that standard text-searching tools simply cannot match. The ability to perform high-confidence renames, find interface implementations, and preview the diagnostic impact of edits without writing to disk significantly reduces the risk of introducing regressions."
  56. ### Tested, not assumed
  57. Every other MCP-LSP implementation lists supported languages in a config file. None of them run the actual language server in CI to verify it works.
  58. agent-lsp CI runs **32 real language servers** against real fixture codebases on every push, and all 32 pass end to end: Go, Python, TypeScript, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Zig, Lua, Elixir, Gleam, Clojure, Dart, Terraform, Nix, Prisma, SQL, MongoDB, MQL, and more. When we say "works with gopls," that's a verified, automated claim, not a hope.
  59. ### Speculative execution
  60. Simulate changes in memory before writing to disk. No other MCP-LSP implementation has this.
  61. `preview_edit` previews the diagnostic impact of any edit. You see exactly what breaks before the file is touched. `simulate_chain` evaluates a sequence of dependent edits (rename a function, update all callers, change the return type) and reports which step first introduces an error.
  62. 8 speculative execution tools. See [docs/guide/speculative-execution.md](./docs/guide/speculative-execution.md) for the full workflow.
  63. ### Interactive refactoring
  64. Some refactorings need answers before the language server can compute them: which struct tags to add and how to name them, which interface to implement, where a declaration should move. gopls v0.24 asks these questions through a new LSP extension ([golang/go#76331](https://github.com/golang/go/issues/76331)), which editors show as dialogs. agent-lsp is a client for it built for agents: `refactor` returns the questions as a typed form (choices, defaults, a searchable list for the interface), the agent answers, and the server computes the edit. agent-lsp captures that edit before it is written, so `dry_run` previews it.
  65. ```
  66. refactor(file, line, column) → available refactorings
  67. refactor(..., action: "Add struct tags") → questions: tags (default "json"), naming style (camelCase, snake_case, ...)
  68. refactor(..., answers: {addTags: "json", transform: "snakecase"}) → applied
  69. ```
  70. See [`refactor`](./docs/reference/tools.md#refactor) in the tool reference.
  71. ### Token savings
  72. Structured LSP responses use **5-34x fewer tokens** than grep/read on the same tasks. On HashiCorp Consul (319K lines), a blast-radius analysis uses 17.7MB via grep vs 841KB via LSP, reducing 5,534 tool calls to 119. Savings scale with codebase size. See [docs/guide/token-savings.md](./docs/guide/token-savings.md) for the full experiment across five codebases.
  73. ### Token-optimized output (GCF)
  74. Tool responses are encoded in [GCF (Graph Compact Format)](https://gcformat.com) instead of JSON. GCF eliminates field-name repetition, identifier repetition, and per-record structural overhead.
  75. | Profile | Tools | Savings vs JSON |
  76. |---------|-------|----------------|
  77. | Tabular | Other structured results (find_references, diagnostics, detect_changes, ...) | **30-51%** |
  78. | Graph | list_symbols, find_symbol, blast_radius, find_callers, explore_symbol, type_hierarchy, get_cross_repo_references | **79-84%** |
  79. | Graph + session dedup | Same, via [gcf-proxy](https://github.com/blackwell-systems/gcf-proxy) `--session` | **92.7%** (5th call) |
  80. Workspace edits (rename and `refactor` previews) are always JSON, so they round-trip into `apply_edit` byte-exact. Grouped/nested responses (callers under a symbol, diagnostics with related info) tabularize too, for ~14% over JSON on that shape ([details](./docs/guide/gcf-integration.md#nested-container-responses-grouped-data)).
  81. GCF is enabled by default. To revert to JSON:
  82. ```bash
  83. export AGENT_LSP_OUTPUT_FORMAT=json
  84. ```
  85. Benchmark: `go run scripts/gcf-benchmark.go`. See [docs/guide/gcf-integration.md](./docs/guide/gcf-integration.md) for architecture details.
  86. **GCF:** [gcformat.com](https://gcformat.com) · [Spec](https://github.com/blackwell-systems/gcf) · [Go](https://github.com/blackwell-systems/gcf-go) · [Python](https://github.com/blackwell-systems/gcf-python) · [TypeScript](https://github.com/blackwell-systems/gcf-typescript) · [Playground](https://gcformat.com/playground.html)
  87. ### Why orchestration matters
  88. AI agents make incorrect code changes because they can't see the full picture: who calls this function, what breaks if I rename it, does the build still pass. Language servers have the answers, but raw LSP tools require 20+ sequential calls and complex orchestration logic.
  89. agent-lsp solves this by encoding correct multi-step operations into single calls and skills. `blast_radius` does what would take an agent 20+ calls in one. `/lsp-refactor` chains impact → preview → apply → verify → test without per-prompt orchestration.
  90. ### Persistent daemon mode
  91. Python and TypeScript projects need minutes of background indexing before `find_references` works. agent-lsp automatically spawns a persistent daemon broker that survives between sessions, so the workspace stays indexed. First session: daemon starts and indexes (~10s for FastAPI). Subsequent sessions: instant connection to the warm daemon. Auto-exits after 30 minutes of inactivity. Go, Rust, and other fast-indexing languages bypass this entirely (zero overhead).
  92. ### Phase enforcement
  93. Skills tell agents the correct order of operations. Phase enforcement makes the runtime *block* violations instead of trusting the agent to follow instructions.
  94. When an agent activates a skill, every tool call is checked against the current phase's permissions. Calling `apply_edit` during blast-radius analysis doesn't silently proceed; it returns an error with specific recovery guidance, followed by a JSON copy of the same fields:
  95. ```
  96. Phase violation: apply_edit is forbidden in the "blast_radius" phase
  97. Recovery: apply_edit becomes available in the "apply" phase. Next phase is "speculative_preview". Allowed tools: [open_document get_diagnostics preview_edit simulate_chain]
  98. ```
  99. Phases advance automatically as the agent calls tools from later phases.
  100. No other MCP tool provider enforces workflow ordering at runtime. See [docs/guide/phase-enforcement.md](./docs/guide/phase-enforcement.md).
  101. ### Concurrency analysis
  102. The inspector includes 4 concurrency checks that work across 25 languages in 4 concurrency families (goroutine, thread, async, actor):
  103. - **Unrecovered concurrent entry**: goroutines/threads/tasks without recovery
  104. - **Unchecked shared state**: bare type assertions on sync.Map, ConcurrentHashMap
  105. - **Channel never closed**: channels/queues created but never closed (goroutine leaks)
  106. - **Shared field without sync**: fields accessed from concurrent contexts without synchronization
  107. `blast_radius` annotates symbols with `sync_guarded: true` when the parent type has a mutex. `find_callers` with `cross_concurrent: true` traces call chains through goroutine/thread boundaries. The `/lsp-concurrency-audit` skill produces a field-level safety report for any type.
  108. ### Auto-diagnostics
  109. Symbol edit tools (`replace_symbol_body`, `insert_after_symbol`, `insert_before_symbol`, `safe_delete_symbol`) automatically return `errors_after` and `warnings_after` counts. Agents know immediately whether an edit broke something without a separate `get_diagnostics` call.
  110. `safe_apply_edit` combines preview + apply in one call: previews speculatively, applies to disk only if `net_delta == 0` (no new errors). It also refuses edits it could not verify (a timed-out preview or a server still indexing) and writes only the content it previewed: if the file changed in between, nothing is written. One tool call instead of three.
  111. ### Works with
  112. | AI Tool | Transport | Setup |
  113. |---------|-----------|-------|
  114. | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | stdio | `agent-lsp init` |
  115. | [Cursor](https://cursor.com) | stdio | `agent-lsp init` |
  116. | [Windsurf](https://windsurf.com) | stdio | `agent-lsp init` |
  117. | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | stdio | `agent-lsp init` |
  118. | [Codex](https://developers.openai.com/codex) and the ChatGPT desktop app | stdio | `agent-lsp init` |
  119. | [Continue](https://continue.dev) | stdio | [manual config](./docs/getting-started/mcp-clients.md) |
  120. | [Cline](https://github.com/cline/cline) | stdio | `agent-lsp init` |
  121. | [Pi](https://github.com/earendil-works/pi) | stdio | `agent-lsp init` + `pi install npm:pi-mcp-adapter` |
  122. | Any MCP client | Streamable HTTP | `AGENT_LSP_TOKEN=secret agent-lsp --http --port 8080` |
  123. See [docs/getting-started/mcp-clients.md](./docs/getting-started/mcp-clients.md) for copy-paste configs.
  124. ## Skills
  125. Raw tools get ignored. Skills get used. Each skill encodes the correct tool sequence so workflows actually happen without per-prompt orchestration instructions. Skills are available as [AgentSkills](https://github.com/anthropics/agent-skills) slash commands and as MCP prompts via `prompts/list` / `prompts/get` for any MCP client.
  126. See [docs/guide/skills.md](./docs/guide/skills.md) for full descriptions and usage guidance.
  127. **Before you change anything**
  128. | Skill | Purpose |
  129. |-------|---------|
  130. | `/lsp-impact` | Blast-radius analysis before touching a symbol or file |
  131. | `/lsp-implement` | Find all concrete implementations of an interface |
  132. | `/lsp-dead-code` | Detect zero-reference exports before cleanup |
  133. **Editing safely**
  134. | Skill | Purpose |
  135. |-------|---------|
  136. | `/lsp-safe-edit` | Speculative preview before disk write; before/after diagnostic diff; surfaces code actions on errors |
  137. | `/lsp-simulate` | Test changes in-memory without touching the file |
  138. | `/lsp-edit-symbol` | Edit a named symbol without knowing its file or position |
  139. | `/lsp-edit-export` | Safe editing of exported symbols, finds all callers first |
  140. | `/lsp-rename` | `prepare_rename` safety gate, preview all sites, confirm, apply atomically |
  141. **Getting started**
  142. | Skill | Purpose |
  143. |-------|---------|
  144. | `/lsp-architecture` | Structural architecture overview: languages, package map, entry points, dependency graph, and hotspots |
  145. | `/lsp-onboard` | First-session project onboarding: detect languages, map packages, find entry points and hotspots, check diagnostics |
  146. **Understanding unfamiliar code**
  147. | Skill | Purpose |
  148. |-------|---------|
  149. | `/lsp-explore` | "Tell me about this symbol": hover + implementations + call hierarchy + references in one pass |
  150. | `/lsp-understand` | Deep-dive Code Map for a symbol or file: type info, call hierarchy, references, source |
  151. | `/lsp-docs` | Three-tier documentation: hover → offline toolchain → source |
  152. | `/lsp-cross-repo` | Find all usages of a library symbol across consumer repos |
  153. | `/lsp-local-symbols` | File-scoped symbol list, usage search, and type info |
  154. **After editing**
  155. | Skill | Purpose |
  156. |-------|---------|
  157. | `/lsp-verify` | Diagnostics + build + tests after every edit |
  158. | `/lsp-fix-all` | Apply quick-fix code actions for all diagnostics in a file |
  159. | `/lsp-test-correlation` | Find and run only tests that cover an edited file |
  160. | `/lsp-format-code` | Format a file or selection via the language server formatter |
  161. **Generating code**
  162. | Skill | Purpose |
  163. |-------|---------|
  164. | `/lsp-generate` | Trigger server-side code generation (interface stubs, test skeletons, mocks) |
  165. | `/lsp-extract-function` | Extract a code block into a named function via code actions |
  166. **Full workflow**
  167. | Skill | Purpose |
  168. |-------|---------|
  169. | `/lsp-refactor` | End-to-end refactor: blast-radius → preview → apply → verify → test |
  170. | `/lsp-inspect` | Full code quality audit (12 checks): dead symbols, test coverage, error handling, doc drift, concurrency safety |
  171. | `/lsp-concurrency-audit` | Field-level concurrency safety audit for a type: traces concurrent access, flags unsynced fields |
  172. ## Docker
  173. **Stdio mode** (MCP client spawns the container directly):
  174. ```bash
  175. # Go
  176. docker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:go go:gopls
  177. # TypeScript
  178. docker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:typescript typescript:typescript-language-server,--stdio
  179. # Python
  180. docker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:python python:pyright-langserver,--stdio
  181. ```
  182. **HTTP mode** (persistent service, remote clients connect over Streamable HTTP):
  183. ```bash
  184. docker run --rm \
  185. -p 8080:8080 \
  186. -v /your/project:/workspace \
  187. -e AGENT_LSP_TOKEN=your-secret-token \
  188. ghcr.io/blackwell-systems/agent-lsp:go \
  189. --http --port 8080 --listen-addr 0.0.0.0 go:gopls
  190. ```
  191. The server binds `127.0.0.1` by default, so pass `--listen-addr 0.0.0.0` inside a container for the port mapping to reach it. Images run as a non-root user (uid 65532) by default. Set `AGENT_LSP_TOKEN` via environment variable, never `--token` on the command line. Images are also mirrored to Docker Hub (`blackwellsystems/agent-lsp`). See [DOCKER.md](./DOCKER.md) for the full tag list, HTTP mode setup, and security hardening options.
  192. ## Setup
  193. ### Step 1: Install agent-lsp
  194. ```bash
  195. curl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh
  196. ```
  197. <details>
  198. <summary>Alternative install methods</summary>
  199. **macOS / Linux**
  200. ```bash
  201. brew install blackwell-systems/tap/agent-lsp
  202. ```
  203. **Windows**
  204. ```powershell
  205. # PowerShell (no admin required)
  206. iwr -useb https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.ps1 | iex
  207. # Scoop
  208. scoop bucket add blackwell-systems https://github.com/blackwell-systems/agent-lsp
  209. scoop install blackwell-systems/agent-lsp
  210. # Winget
  211. winget install BlackwellSystems.agent-lsp
  212. ```
  213. **All platforms**
  214. ```bash
  215. # pip
  216. pip install agent-lsp
  217. # npm
  218. npm install -g @blackwell-systems/agent-lsp
  219. # Go install
  220. go install github.com/blackwell-systems/agent-lsp/cmd/agent-lsp@latest
  221. ```
  222. </details>
  223. ### Step 2: Install language servers
  224. Install the servers for your stack. Common ones:
  225. | Language | Server | Install |
  226. |----------|--------|---------|
  227. | TypeScript / JavaScript | `typescript-language-server` | `npm i -g typescript-language-server typescript@6` |
  228. | Python | `pyright-langserver` | `npm i -g pyright` |
  229. | Go | `gopls` | `go install golang.org/x/tools/gopls@latest` |
  230. | Rust | `rust-analyzer` | `rustup component add rust-analyzer` |
  231. | C / C++ | `clangd` | `apt install clangd` / `brew install llvm` |
  232. | Ruby | `solargraph` | `gem install solargraph` |
  233. TypeScript 7 ships without `tsserver`, which typescript-language-server needs, so install TypeScript 6 (`typescript@6`) until that changes. A project with TypeScript 6 in its own `node_modules` works either way.
  234. Full list of supported languages and their CI status in [docs/reference/language-support.md](./docs/reference/language-support.md).
  235. ### Step 3: Verify setup
  236. ```bash
  237. agent-lsp doctor
  238. ```
  239. Probes each configured language server and reports capabilities. Fix any failures before proceeding. See [language support](./docs/reference/language-support.md) for install commands and server-specific notes.
  240. ### Step 4: Configure your AI tool
  241. ```bash
  242. agent-lsp init
  243. ```
  244. Detects language servers on your PATH, asks which AI tool you use, writes the correct MCP config, and installs skill awareness rules for your AI provider (CLAUDE.md for Claude Code, `.cursor/rules/` for Cursor, `.clinerules` for Cline, `.windsurfrules` for Windsurf, `GEMINI.md` for Gemini CLI, `AGENTS.md` for Pi and Codex). For CI or scripted use: `agent-lsp init --non-interactive`.
  245. For Claude Code, choose the project target (`1`, writes `.mcp.json` in the current directory) or the user scope (`2`, all projects: registers the server with `claude mcp add --scope user` when the `claude` CLI is installed, otherwise adds it to `~/.claude.json`). `init` only sets the `agent-lsp` entry; every other server and setting in an existing config file is kept.
  246. For Codex and the ChatGPT desktop app, which share one MCP configuration, choose the user target (`11`: registers the server with `codex mcp add` when the `codex` CLI is installed, otherwise adds an `[mcp_servers.agent-lsp]` table to `$CODEX_HOME/config.toml`, default `~/.codex/config.toml`) or the project target (`12`: `.codex/config.toml` in the current directory, read for trusted projects). The TOML file is edited in place, so your other settings and comments are kept.
  247. For [Pi](https://github.com/earendil-works/pi), choose the project (`9`) or global (`10`) target. Pi has no built-in MCP support; `init` writes the shared standard MCP files that the [`pi-mcp-adapter`](https://www.npmjs.com/package/pi-mcp-adapter) package reads — project `.mcp.json` (same file Claude Code uses, so one config serves both) or global `~/.config/mcp/mcp.json`. Skill awareness rules go into `AGENTS.md` (project) or `~/.pi/agent/AGENTS.md` (global). Install the adapter once with `pi install npm:pi-mcp-adapter`.
  248. #### One-command complete setup
  249. Add `--with-skills` to also install the embedded skill files (no repo clone needed):
  250. ```bash
  251. agent-lsp init --with-skills
  252. ```
  253. Skills are written to the destination matching the chosen target: only the Pi project target (`9`) uses the tool-agnostic `.agents/skills/` directory (versionable with the repo); the Pi global target (`10`) uses `~/.pi/agent/skills/`; the Claude Code targets (`1`/`2`) use `~/.claude/skills/`; Cursor (`4`) uses `~/.cursor/skills/`; Gemini CLI (`7`) uses `~/.config/gemini-cli/skills/`; and the Codex user target (`11`) uses `$CODEX_HOME/skills/`. Providers without a verified skills directory are skipped with a pointer to `skills/install.sh --dest`. Re-running overwrites the managed skill files, keeping them in sync with the installed binary. `agent-lsp uninstall` removes them.
  254. The generated config looks like:
  255. ```json
  256. {
  257. "mcpServers": {
  258. "agent-lsp": {
  259. "type": "stdio",
  260. "command": "agent-lsp",
  261. "args": [
  262. "go:gopls",
  263. "typescript:typescript-language-server,--stdio",
  264. "python:pyright-langserver,--stdio"
  265. ]
  266. }
  267. }
  268. }
  269. ```
  270. Each arg is `language:server-binary` (comma-separate server args).
  271. ### Step 5: Install skills
  272. ```bash
  273. git clone https://github.com/blackwell-systems/agent-lsp.git /tmp/agent-lsp-skills
  274. cd /tmp/agent-lsp-skills/skills && ./install.sh --copy
  275. ```
  276. Or skip the clone entirely: `agent-lsp init --with-skills` installs the same embedded skills to the destination matching your chosen target.
  277. Skills are prompt files copied into your AI tool's configuration. `--copy` means the clone can be safely deleted afterward. The script defaults to `~/.claude/skills/`; pass `--dest` for other agents, e.g. `--dest ~/.pi/agent/skills` for Pi. It also appends a managed skills table to existing instruction files (`~/.claude/CLAUDE.md`, project `AGENTS.md`, `~/.pi/agent/AGENTS.md`, `GEMINI.md`).
  278. Skills are also available as **MCP prompts**: any MCP client can discover them via `prompts/list` and retrieve full workflow instructions via `prompts/get`, with no manual installation required. The `install.sh` path is for AgentSkills-compatible clients (Claude Code slash commands, Pi `/skill:name` commands).
  279. ### Step 6: Allow tool permissions (Claude Code)
  280. For Claude Code, add `mcp__agent-lsp__*` to your permissions allow list so all 66 tools are available without per-tool approval prompts:
  281. ```json
  282. // ~/.claude/settings.json
  283. {
  284. "permissions": {
  285. "allow": ["mcp__agent-lsp__*"]
  286. }
  287. }
  288. ```
  289. Without this, Claude Code will prompt for permission on each tool call. Other MCP clients handle permissions differently; check your client's documentation.
  290. Skills are multi-tool workflows that encode reliable procedures: blast-radius check before edit, speculative preview before write, test run after change. See [docs/guide/skills.md](./docs/guide/skills.md) for the full list.
  291. ### Step 7: Start working
  292. Your AI agent calls tools automatically. The first call initializes the workspace:
  293. ```
  294. start_lsp(root_dir="/your/project")
  295. ```
  296. This is what the agent does, not something you type. Then use any of the 66 tools. The session stays warm; no restart needed when switching files.
  297. ## What's unique about agent-lsp
  298. | Capability | Details |
  299. |------------|---------|
  300. | Tools | **66** |
  301. | Languages (CI-verified) | **32**, end-to-end integration tests on every push |
  302. | Agent workflows (skills) | **24**, named multi-step procedures, discoverable via MCP `prompts/list` |
  303. | Speculative execution | **8 tools**, simulate changes before writing to disk |
  304. | Interactive refactoring | **✓**, answers the language server's refactoring questions (gopls v0.24+) |
  305. | Phase enforcement | **4 skills**, runtime blocks out-of-order tool calls with recovery guidance |
  306. | Connection model | **persistent**, warm index across files and projects |
  307. | Call hierarchy | **✓**, single tool, direction param |
  308. | Type hierarchy | **✓**, CI-verified |
  309. | Cross-repo references | **✓**, multi-root workspace |
  310. | Multi-server queries | **✓**, `find_symbol` and `get_server_capabilities` ask every running language server |
  311. | Auto-watch | **✓**, always-on, debounced file watching |
  312. | Streamable HTTP transport | **✓**, bearer token auth, non-root Docker |
  313. | Distribution | **single Go binary**, 10 install channels |
  314. ## Use Cases
  315. - **Multi-project sessions**: point your AI at `~/code/`, work across any project without reconfiguring
  316. - **Polyglot development**: Go backend + TypeScript frontend + Python scripts in one session
  317. - **Large monorepos**: one server handles all languages, routes by file extension
  318. - **Code migration**: refactor across repos with full cross-repo reference tracking
  319. - **CI pipelines**: validate against real language server behavior
  320. - **Niche language stacks**: Gleam, Elixir, Prisma, Zig, Clojure, Nix, Dart, Scala, MongoDB, all CI-verified
  321. ## Multi-Language Support
  322. 32 languages CI-verified end to end against real language servers on every CI run. A language that fails to start or answer fails CI rather than being skipped. No other MCP-LSP implementation tests a single language in CI.
  323. Go, Python, TypeScript, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Zig, Lua, Elixir, Gleam, Clojure, Dart, Terraform, Nix, Prisma, SQL, MongoDB, JavaScript, YAML, JSON, Dockerfile, CSS, HTML, MQL, Luau.
  324. See [docs/reference/language-support.md](./docs/reference/language-support.md) for the full coverage matrix.
  325. ## Tools
  326. 66 tools covering navigation, analysis, refactoring, symbol editing, composite exploration, safe editing, speculative execution, and session lifecycle. All CI-verified.
  327. See [docs/reference/tools.md](./docs/reference/tools.md) for the full reference with parameters and examples.
  328. ## Further reading
  329. ### Documentation
  330. - [Tools reference](./docs/reference/tools.md): full tool reference with parameters and examples
  331. - [Skills reference](./docs/guide/skills.md): skill reference, workflows, use cases, and composition
  332. - [Language support](./docs/reference/language-support.md): language coverage matrix
  333. - [Architecture](./docs/architecture/architecture.md): system design and internals
  334. - [Speculative execution](./docs/guide/speculative-execution.md): simulate-before-apply workflows
  335. - [LSP conformance](./docs/reference/lsp-conformance.md): LSP 3.17 spec coverage
  336. - [Docker](./DOCKER.md): Docker tags, compose, and volume caching
  337. ### Contributing
  338. - [CI notes](./docs/architecture/ci-notes.md): CI quirks and test harness details
  339. - [Distribution](./docs/architecture/distribution.md): install channels and release pipeline
  340. ## Development
  341. ```bash
  342. git clone https://github.com/blackwell-systems/agent-lsp.git
  343. cd agent-lsp && go build ./...
  344. go test ./... # unit tests
  345. go test ./... -tags integration # integration tests (requires language servers)
  346. ```
  347. ## Library Usage
  348. The `pkg/lsp`, `pkg/session`, and `pkg/types` packages expose a stable Go API for using agent-lsp's LSP client directly without running the MCP server.
  349. ```go
  350. import "github.com/blackwell-systems/agent-lsp/pkg/lsp"
  351. client := lsp.NewLSPClient("gopls", []string{})
  352. client.Initialize(ctx, "/path/to/workspace")
  353. defer client.Shutdown(ctx)
  354. locs, err := client.GetDefinition(ctx, fileURI, lsp.Position{Line: 10, Character: 4})
  355. ```
  356. See [docs/architecture/architecture.md](./docs/architecture/architecture.md) for the full package API.
  357. ## License
  358. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.