{ "markdown": "

\n \"agent-lsp\"\n

\n\n

\n \"CI\n \"Languages\"\n \"mcp-assert:\n \"Agent\n \"downloads\"\n
\n \"LSP\n \"License\"\n \"Awesome\n \"Blackwell\n

\n\n**Code intelligence infrastructure for AI agents.** 65 tools, 31 CI-verified languages, 24 agent workflows. Single Go binary.\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh && agent-lsp init\n```\n\n## What is it?\n\nagent-lsp is an **MCP server** that orchestrates existing LSP servers (gopls, rust-analyzer, jdtls, etc.) into agent-native workflows.\n\n**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.\n\n**Architecture:**\n- **Language servers** (gopls, rust-analyzer, etc.) → provide code intelligence\n- **agent-lsp** (MCP server) → orchestrates workflows, maintains warm runtime\n- **AI agents** → consume via MCP protocol\n\n## Why agent-lsp?\n\n**Persistent warm runtime** \nLanguage servers stay indexed across agent sessions. First session: indexes workspace (~10s for typical projects). Subsequent sessions: instant. No cold-start penalty on each request.\n\n**Batch operations** \n`blast_radius` → one call returns all exports + all callers (test vs non-test partitioned). Without orchestration: 20+ sequential LSP calls.\n\n**Speculative editing** \n`simulate_edit` → preview changes in memory, check diagnostic delta, apply or discard. Test edits before touching disk.\n\n**Workflow orchestration** \n24 skills that chain LSP operations into complete pipelines:\n- `/lsp-refactor` → impact analysis → preview → apply → verify build → run tests\n- `/lsp-safe-edit` → preview → diagnostic diff → apply if safe\n- `/lsp-verify` → LSP diagnostics → build → test suite\n\n**Multi-language, single session** \nOne agent-lsp process routes `.go` to gopls, `.ts` to tsserver, `.py` to pyright. No reconfiguration between projects. Session persists across files and repositories.\n\n> [!TIP]\n> **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.\n\n**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.\n\n## Use it when\n\n- Building agentic code generation systems\n- Automating refactors across large codebases\n- CI tooling that needs programmatic code intelligence\n- Any workflow where sequential LSP calls are too slow or complex\n\n### What agents say\n\nWe 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:\n\n> **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).\"\n\n> **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.\"\n\n> **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.\"\n\n> **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.\"\n\n### Tested, not assumed\n\nEvery 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.\n\nagent-lsp CI runs **31 real language servers** against real fixture codebases on every push: Go, Python, TypeScript, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Zig, Lua, Elixir, Gleam, Clojure, Dart, Terraform, Nix, Prisma, SQL, MongoDB, and more. When we say \"works with gopls,\" that's a verified, automated claim, not a hope.\n\n### Speculative execution\n\nSimulate changes in memory before writing to disk. No other MCP-LSP implementation has this.\n\n`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.\n\n8 speculative execution tools. See [docs/guide/speculative-execution.md](./docs/guide/speculative-execution.md) for the full workflow.\n\n### Token savings\n\nStructured 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.\n\n### Token-optimized output (GCF)\n\nTool 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.\n\n| Profile | Tools | Savings vs JSON |\n|---------|-------|----------------|\n| Tabular | All 66 tools | **30-51%** |\n| Graph | blast_radius, find_callers, explore_symbol, find_references, type_hierarchy, cross_repo, detect_changes, list_symbols | **79-84%** |\n| Graph + session dedup | Same, via [gcf-proxy](https://github.com/blackwell-systems/gcf-proxy) `--session` | **92.7%** (5th call) |\n\nGrouped/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)).\n\nGCF is enabled by default. To revert to JSON:\n\n```bash\nexport AGENT_LSP_OUTPUT_FORMAT=json\n```\n\nBenchmark: `go run scripts/gcf-benchmark.go`. See [docs/guide/gcf-integration.md](./docs/guide/gcf-integration.md) for architecture details.\n\n**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)\n\n### Why orchestration matters\n\nAI 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.\n\nagent-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.\n\n### Persistent daemon mode\n\nPython 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).\n\n### Phase enforcement\n\nSkills tell agents the correct order of operations. Phase enforcement makes the runtime *block* violations instead of trusting the agent to follow instructions.\n\nWhen 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 (\"complete the blast_radius phase first, allowed tools: [blast_radius, find_references]\"). Phases advance automatically as the agent calls tools from later phases.\n\nNo other MCP tool provider enforces workflow ordering at runtime. See [docs/guide/phase-enforcement.md](./docs/guide/phase-enforcement.md).\n\n### Concurrency analysis\n\nThe inspector includes 4 concurrency checks that work across 25 languages in 4 concurrency families (goroutine, thread, async, actor):\n\n- **Unrecovered concurrent entry**: goroutines/threads/tasks without recovery\n- **Unchecked shared state**: bare type assertions on sync.Map, ConcurrentHashMap\n- **Channel never closed**: channels/queues created but never closed (goroutine leaks)\n- **Shared field without sync**: fields accessed from concurrent contexts without synchronization\n\n`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.\n\n### Auto-diagnostics\n\nSymbol 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.\n\n`safe_apply_edit` combines preview + apply in one call: previews speculatively, applies to disk only if `net_delta == 0` (no new errors). One tool call instead of three.\n\n### Works with\n\n| AI Tool | Transport | Setup |\n|---------|-----------|-------|\n| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | stdio | `agent-lsp init` |\n| [Cursor](https://cursor.com) | stdio | `agent-lsp init` |\n| [Windsurf](https://windsurf.com) | stdio | `agent-lsp init` |\n| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | stdio | `agent-lsp init` |\n| [Continue](https://continue.dev) | stdio | `agent-lsp init` |\n| [Cline](https://github.com/cline/cline) | stdio | `agent-lsp init` |\n| Any MCP client | HTTP+SSE | `agent-lsp --http --port 8080` |\n\nSee [docs/getting-started/mcp-clients.md](./docs/getting-started/mcp-clients.md) for copy-paste configs.\n\n## Skills\n\nRaw 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.\n\nSee [docs/guide/skills.md](./docs/guide/skills.md) for full descriptions and usage guidance.\n\n**Before you change anything**\n\n| Skill | Purpose |\n|-------|---------|\n| `/lsp-impact` | Blast-radius analysis before touching a symbol or file |\n| `/lsp-implement` | Find all concrete implementations of an interface |\n| `/lsp-dead-code` | Detect zero-reference exports before cleanup |\n\n**Editing safely**\n\n| Skill | Purpose |\n|-------|---------|\n| `/lsp-safe-edit` | Speculative preview before disk write; before/after diagnostic diff; surfaces code actions on errors |\n| `/lsp-simulate` | Test changes in-memory without touching the file |\n| `/lsp-edit-symbol` | Edit a named symbol without knowing its file or position |\n| `/lsp-edit-export` | Safe editing of exported symbols, finds all callers first |\n| `/lsp-rename` | `prepare_rename` safety gate, preview all sites, confirm, apply atomically |\n\n**Getting started**\n\n| Skill | Purpose |\n|-------|---------|\n| `/lsp-onboard` | First-session project onboarding: detect languages, map packages, find entry points and hotspots, check diagnostics |\n\n**Understanding unfamiliar code**\n\n| Skill | Purpose |\n|-------|---------|\n| `/lsp-explore` | \"Tell me about this symbol\": hover + implementations + call hierarchy + references in one pass |\n| `/lsp-understand` | Deep-dive Code Map for a symbol or file: type info, call hierarchy, references, source |\n| `/lsp-docs` | Three-tier documentation: hover → offline toolchain → source |\n| `/lsp-cross-repo` | Find all usages of a library symbol across consumer repos |\n| `/lsp-local-symbols` | File-scoped symbol list, usage search, and type info |\n\n**After editing**\n\n| Skill | Purpose |\n|-------|---------|\n| `/lsp-verify` | Diagnostics + build + tests after every edit |\n| `/lsp-fix-all` | Apply quick-fix code actions for all diagnostics in a file |\n| `/lsp-test-correlation` | Find and run only tests that cover an edited file |\n| `/lsp-format-code` | Format a file or selection via the language server formatter |\n\n**Generating code**\n\n| Skill | Purpose |\n|-------|---------|\n| `/lsp-generate` | Trigger server-side code generation (interface stubs, test skeletons, mocks) |\n| `/lsp-extract-function` | Extract a code block into a named function via code actions |\n\n**Full workflow**\n\n| Skill | Purpose |\n|-------|---------|\n| `/lsp-refactor` | End-to-end refactor: blast-radius → preview → apply → verify → test |\n| `/lsp-inspect` | Full code quality audit (12 checks): dead symbols, test coverage, error handling, doc drift, concurrency safety |\n| `/lsp-concurrency-audit` | Field-level concurrency safety audit for a type: traces concurrent access, flags unsynced fields |\n\n## Docker\n\n**Stdio mode** (MCP client spawns the container directly):\n\n```bash\n# Go\ndocker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:go go:gopls\n\n# TypeScript\ndocker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:typescript typescript:typescript-language-server,--stdio\n\n# Python\ndocker run --rm -i -v /your/project:/workspace ghcr.io/blackwell-systems/agent-lsp:python python:pyright-langserver,--stdio\n```\n\n**HTTP mode** (persistent service, remote clients connect over HTTP+SSE):\n\n```bash\ndocker run --rm \\\n -p 8080:8080 \\\n -v /your/project:/workspace \\\n -e AGENT_LSP_TOKEN=your-secret-token \\\n ghcr.io/blackwell-systems/agent-lsp:go \\\n --http --port 8080 go:gopls\n```\n\nImages 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.\n\n## Setup\n\n### Step 1: Install agent-lsp\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh\n```\n\n
\nAlternative install methods\n\n**macOS / Linux**\n\n```bash\nbrew install blackwell-systems/tap/agent-lsp\n```\n\n**Windows**\n\n```powershell\n# PowerShell (no admin required)\niwr -useb https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.ps1 | iex\n\n# Scoop\nscoop bucket add blackwell-systems https://github.com/blackwell-systems/agent-lsp\nscoop install blackwell-systems/agent-lsp\n\n# Winget\nwinget install BlackwellSystems.agent-lsp\n```\n\n**All platforms**\n\n```bash\n# pip\npip install agent-lsp\n\n# npm\nnpm install -g @blackwell-systems/agent-lsp\n\n# Go install\ngo install github.com/blackwell-systems/agent-lsp/cmd/agent-lsp@latest\n```\n\n
\n\n### Step 2: Install language servers\n\nInstall the servers for your stack. Common ones:\n\n| Language | Server | Install |\n|----------|--------|---------|\n| TypeScript / JavaScript | `typescript-language-server` | `npm i -g typescript-language-server typescript` |\n| Python | `pyright-langserver` | `npm i -g pyright` |\n| Go | `gopls` | `go install golang.org/x/tools/gopls@latest` |\n| Rust | `rust-analyzer` | `rustup component add rust-analyzer` |\n| C / C++ | `clangd` | `apt install clangd` / `brew install llvm` |\n| Ruby | `solargraph` | `gem install solargraph` |\n\nFull list of 31 supported languages in [docs/reference/language-support.md](./docs/reference/language-support.md).\n\n### Step 3: Verify setup\n\n```bash\nagent-lsp doctor\n```\n\nProbes 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.\n\n### Step 4: Configure your AI tool\n\n```bash\nagent-lsp init\n```\n\nDetects 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). For CI or scripted use: `agent-lsp init --non-interactive`.\n\nThe generated config looks like:\n\n```json\n{\n \"mcpServers\": {\n \"lsp\": {\n \"type\": \"stdio\",\n \"command\": \"agent-lsp\",\n \"args\": [\n \"go:gopls\",\n \"typescript:typescript-language-server,--stdio\",\n \"python:pyright-langserver,--stdio\"\n ]\n }\n }\n}\n```\n\nEach arg is `language:server-binary` (comma-separate server args).\n\n### Step 5: Install skills\n\n```bash\ngit clone https://github.com/blackwell-systems/agent-lsp.git /tmp/agent-lsp-skills\ncd /tmp/agent-lsp-skills/skills && ./install.sh --copy\n```\n\nSkills are prompt files copied into your AI tool's configuration. `--copy` means the clone can be safely deleted afterward.\n\nSkills 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).\n\n### Step 6: Allow tool permissions (Claude Code)\n\nFor Claude Code, add `mcp__lsp__*` to your permissions allow list so all 65 tools are available without per-tool approval prompts:\n\n```json\n// ~/.claude/settings.json\n{\n \"permissions\": {\n \"allow\": [\"mcp__lsp__*\"]\n }\n}\n```\n\nWithout this, Claude Code will prompt for permission on each tool call. Other MCP clients handle permissions differently; check your client's documentation.\n\nSkills 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.\n\n### Step 7: Start working\n\nYour AI agent calls tools automatically. The first call initializes the workspace:\n\n```\nstart_lsp(root_dir=\"/your/project\")\n```\n\nThis is what the agent does, not something you type. Then use any of the 65 tools. The session stays warm; no restart needed when switching files.\n\n## What's unique about agent-lsp\n\n| Capability | Details |\n|------------|---------|\n| Tools | **65** |\n| Languages (CI-verified) | **30**, end-to-end integration tests on every push |\n| Agent workflows (skills) | **24**, named multi-step procedures, discoverable via MCP `prompts/list` |\n| Speculative execution | **8 tools**, simulate changes before writing to disk |\n| Phase enforcement | **4 skills**, runtime blocks out-of-order tool calls with recovery guidance |\n| Connection model | **persistent**, warm index across files and projects |\n| Call hierarchy | **✓**, single tool, direction param |\n| Type hierarchy | **✓**, CI-verified |\n| Cross-repo references | **✓**, multi-root workspace |\n| Auto-watch | **✓**, always-on, debounced file watching |\n| HTTP+SSE transport | **✓**, bearer token auth, non-root Docker |\n| Distribution | **single Go binary**, 10 install channels |\n\n## Use Cases\n\n- **Multi-project sessions**: point your AI at `~/code/`, work across any project without reconfiguring\n- **Polyglot development**: Go backend + TypeScript frontend + Python scripts in one session\n- **Large monorepos**: one server handles all languages, routes by file extension\n- **Code migration**: refactor across repos with full cross-repo reference tracking\n- **CI pipelines**: validate against real language server behavior\n- **Niche language stacks**: Gleam, Elixir, Prisma, Zig, Clojure, Nix, Dart, Scala, MongoDB, all CI-verified\n\n## Multi-Language Support\n\n31 languages, CI-verified end-to-end against real language servers on every CI run. No other MCP-LSP implementation tests a single language in CI.\n\nGo, 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.\n\nSee [docs/reference/language-support.md](./docs/reference/language-support.md) for the full coverage matrix.\n\n## Tools\n\n65 tools covering navigation, analysis, refactoring, symbol editing, composite exploration, safe editing, speculative execution, and session lifecycle. All CI-verified.\n\nSee [docs/reference/tools.md](./docs/reference/tools.md) for the full reference with parameters and examples.\n\n## Further reading\n\n### Documentation\n\n- [Tools reference](./docs/reference/tools.md): full tool reference with parameters and examples\n- [Skills reference](./docs/guide/skills.md): skill reference, workflows, use cases, and composition\n- [Language support](./docs/reference/language-support.md): language coverage matrix\n- [Architecture](./docs/architecture/architecture.md): system design and internals\n- [Speculative execution](./docs/guide/speculative-execution.md): simulate-before-apply workflows\n- [LSP conformance](./docs/reference/lsp-conformance.md): LSP 3.17 spec coverage\n- [Docker](./DOCKER.md): Docker tags, compose, and volume caching\n\n### Contributing\n\n- [CI notes](./docs/architecture/ci-notes.md): CI quirks and test harness details\n- [Distribution](./docs/architecture/distribution.md): install channels and release pipeline\n\n## Development\n\n```bash\ngit clone https://github.com/blackwell-systems/agent-lsp.git\ncd agent-lsp && go build ./...\ngo test ./... # unit tests\ngo test ./... -tags integration # integration tests (requires language servers)\n```\n\n## Library Usage\n\nThe `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.\n\n```go\nimport \"github.com/blackwell-systems/agent-lsp/pkg/lsp\"\n\nclient := lsp.NewLSPClient(\"gopls\", []string{})\nclient.Initialize(ctx, \"/path/to/workspace\")\ndefer client.Shutdown(ctx)\n\nlocs, err := client.GetDefinition(ctx, fileURI, lsp.Position{Line: 10, Character: 4})\n```\n\nSee [docs/architecture/architecture.md](./docs/architecture/architecture.md) for the full package API.\n\n## License\n\nMIT\n", "bytes": 24719, "sha": "8422c84e50b3afdcbf85d24ae0aa296c4c01c84d2169b04ee6baeb772d327b32", "repo_slug": "blackwell-systems/agent-lsp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_blackwell_systems_agent_lsp_2f9a4b72/readme" }