Agent Lsp

English · 简体中文 · Русский · हिन्दी · العربية

Code intelligence infrastructure for AI agents. 66 tools, 32 CI-verified languages, 24 agent workflows. Single Go binary.

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

What is it?

agent-lsp is an MCP server that orchestrates existing LSP servers (gopls, rust-analyzer, jdtls, etc.) into agent-native workflows.

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.

Architecture:

• Language servers (gopls, rust-analyzer, etc.) → provide code intelligence
• agent-lsp (MCP server) → orchestrates workflows, maintains warm runtime
• AI agents → consume via MCP protocol

Why agent-lsp?

Persistent warm runtime 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.

Batch operations blast_radius → one call returns all exports + all callers (test vs non-test partitioned). Without orchestration: 20+ sequential LSP calls.

Speculative editing 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.

Workflow orchestration 24 skills that chain LSP operations into complete pipelines:

• /lsp-refactor → impact analysis → preview → apply → verify build → run tests
• /lsp-safe-edit → preview → diagnostic diff → apply if safe
• /lsp-verify → LSP diagnostics → build → test suite

Multi-language, single session 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.

[!TIP]

Token-optimized output: Tool responses encoded in GCF instead of JSON. 30-84% fewer tokens depending on tool (up to 92.7% with session dedup). 100% LLM comprehension on every frontier model, 91.2% on complex code graphs where JSON averages 54.1%. See below for measured savings per tool.

How the pieces fit together: LSP (Language Server Protocol) is how editors get code intelligence: completions, diagnostics, go-to-definition. MCP (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.

Use it when

• Building agentic code generation systems
• Automating refactors across large codebases
• CI tooling that needs programmatic code intelligence
• Any workflow where sequential LSP calls are too slow or complex

What agents say

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:

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)."

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."

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."

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."

Tested, not assumed

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.

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.

Speculative execution

Simulate changes in memory before writing to disk. No other MCP-LSP implementation has this.

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.

8 speculative execution tools. See docs/guide/speculative-execution.md for the full workflow.

Interactive refactoring

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), 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.

refactor(file, line, column)                          → available refactorings

refactor(..., action: "Add struct tags") → questions: tags (default "json"), naming style (camelCase, snake_case, ...) refactor(..., answers: {addTags: "json", transform: "snakecase"}) → applied

See refactor in the tool reference.

Token savings

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 for the full experiment across five codebases.

Token-optimized output (GCF)

Tool responses are encoded in GCF (Graph Compact Format) instead of JSON. GCF eliminates field-name repetition, identifier repetition, and per-record structural overhead.

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).

GCF is enabled by default. To revert to JSON:

export AGENT_LSP_OUTPUT_FORMAT=json

Benchmark: go run scripts/gcf-benchmark.go. See docs/guide/gcf-integration.md for architecture details.

GCF: gcformat.com · Spec · Go · Python · TypeScript · Playground

Why orchestration matters

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.

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.

Persistent daemon mode

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).

Phase enforcement

Skills tell agents the correct order of operations. Phase enforcement makes the runtime *block* violations instead of trusting the agent to follow instructions.

When an agent activates a skill, every tool call is checked agains