agent-lsp
Orchestrates gopls, rust-analyzer and other language servers into agent-native code-intelligence workflows: 66 MCP tools, 33 CI-verified languages, 24 agent skills.
- Source repo
- blackwell-systems/agent-lsp
- Stars
- ★ 182
- Last updated
- today
- License
- MIT
- Primary language
- Go
- FA score
- 67/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformChatGPT · Codex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Teams building agentic code-generation systems that need semantic renames and interface-implementation lookup instead of grep
- Not a fit if
- Developers who want a standalone IDE plugin rather than an MCP-based server
- Locked-down environments where language servers and their runtimes cannot be installed
- Website
- agent-lsp.com ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-21
- Source review
- 67/100 · Some gaps
What does this agent do, and when should you use it?
agent-lsp is a Go-based MCP server — not an LSP server itself, but an orchestration layer that manages language servers like gopls, rust-analyzer and pyright, exposing batch operations, speculative editing and multi-step workflows to AI agents over MCP. Language-server indexes persist across sessions via a daemon mode, eliminating cold-start penalties on every request. Tool responses default to GCF (Graph Compact Format), saving 30-84% of tokens versus JSON, up to 92.7% on graph queries. All 33 supported languages run end-to-end integration tests against real language servers on every CI push. Runtime phase enforcement blocks out-of-order tool calls (e.g. apply_edit during blast-radius analysis) with recovery guidance. It ships as a single Go binary with stdio and Streamable HTTP (bearer-token) transports.
Running as an MCP server, start_lsp(root_dir=...) initializes a workspace and routes by file extension (.go → gopls, .ts → tsserver, .py → pyright). Core operations: blast_radius returns all exports plus all callers in one call, partitioned into test vs non-test; preview_edit / simulate_chain speculatively evaluate edits in memory and report diagnostic deltas without touching disk; safe_apply_edit writes only when the net diagnostic delta is zero; refactor acts as a client for the gopls v0.24 interactive-refactoring extension, returning the server's questions as a typed form for the agent to answer; cross-repo references, type hierarchy and call hierarchy queries span every running language server. 24 skills (e.g. /lsp-refactor, /lsp-safe-edit, /lsp-verify, /lsp-concurrency-audit) chain multi-step LSP operations into complete pipelines, exposed as MCP prompts and AgentSkills slash commands. Symbol edit tools automatically return errors_after / warnings_after counts; the inspector includes 4 concurrency checks across 25 languages in 4 concurrency families.
- Teams building agentic code-generation systems that need semantic renames and interface-implementation lookup instead of grep
- Automating refactors across large codebases (Consul-scale experiments reduced 5,534 grep tool calls to 119)
- Full-stack developers working across Go + TypeScript + Python in one session without reconfiguring
- CI engineers who need programmatic validation against real language-server behavior
- Teams on niche stacks (Gleam, Elixir, Nix, Prisma) wanting CI-verified language-server support
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh && agent-lsp initnpm i -g typescript-language-server typescript@6npm i -g pyrightgo install golang.org/x/tools/gopls@latest
- Environment variables
AGENT_LSP_TOKEN- Config files
.mcp.json~/.claude/settings.json- Install notes cover
- Windows · macOS · Linux · Docker
How do you install or deploy this agent?
One-line install (macOS/Linux), then initialize:
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/agent-lsp/main/install.sh | sh && agent-lsp initAlternative channels: Homebrew, pip, npm, go install, Scoop, Winget, and Docker (ghcr.io/blackwell-systems/agent-lsp). Install the language servers you need:
npm i -g typescript-language-server typescript@6
npm i -g pyright
go install golang.org/x/tools/gopls@latestNote: TypeScript 7 ships without tsserver, so install TypeScript 6. Verify the setup:
agent-lsp doctorHTTP mode requires the AGENT_LSP_TOKEN environment variable for bearer-token auth.
How do you use this agent?
Run agent-lsp init to detect language servers on PATH and write the MCP config (targets include Claude Code's .mcp.json, Cursor, Cline, Windsurf, Gemini CLI, and Codex); agent-lsp init --with-skills also installs skill files. Typical MCP config:
{
"mcpServers": {
"agent-lsp": {
"type": "stdio",
"command": "agent-lsp",
"args": [
"go:gopls",
"typescript:typescript-language-server,--stdio",
"python:pyright-langserver,--stdio"
]
}
}
}For Claude Code, allow mcp__agent-lsp__* in ~/.claude/settings.json. On first use the agent calls start_lsp(root_dir="/your/project"); the first session indexes the workspace (~10s typical), then connects instantly to the warm daemon. To revert to JSON output:
export AGENT_LSP_OUTPUT_FORMAT=jsonDocker HTTP mode example:
docker run --rm -p 8080:8080 -v /your/project:/workspace -e AGENT_LSP_TOKEN=your-secret-token ghcr.io/blackwell-systems/agent-lsp:go --http --port 8080 --listen-addr 0.0.0.0 go:goplsWhat are this agent's strengths and limitations?
- All 33 languages are verified end-to-end against real language servers in CI on every push, not just listed in a config file
- Speculative execution (8 tools) previews diagnostic impact of edits without writing to disk — unique among MCP-LSP implementations per the README
- GCF output saves up to 92.7% of tokens on graph queries; structured LSP responses use 5-34x fewer tokens than grep/read
- Phase enforcement blocks out-of-order tool calls at runtime with specific recovery guidance instead of trusting instructions
- Persistent daemon mode makes minute-indexing languages like Python/TypeScript instant on subsequent sessions
- You must install and maintain each language server and its runtime dependencies (npm, go, rustup, etc.) before
agent-lsp doctorpasses - First sessions on Python/TypeScript projects require minutes of background indexing — a real cold-start wait
- Tool calls need MCP client permission setup (e.g. Claude Code's allow list) or every call prompts for approval
- Edit responses (rename/refactor previews) are always JSON rather than GCF, and nested grouped data can cost ~14% more than JSON in GCF
- Skills and phase enforcement impose a specific workflow ordering that may clash with free-form prompting habits
How does this agent compare with similar options?
The README states that other MCP-LSP implementations list supported languages in config files without running them in CI, and lack speculative execution; agent-lsp differentiates on CI-verified support for 33 languages, speculative execution, and phase enforcement. The comparison is against a generic class of 'other MCP-LSP implementations' — no named competitors.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| agent-lsp This agent | 67 · Some gaps | MCP serverFree | ★ 182 | today | Go | ChatGPT · Codex · Claude Code |
| Gortex Code Intelligence | 73 · Some gaps | CLIFree | ★ 2.1k | today | Go | Codex · Claude Code · OpenAI API · Claude API |
| Argot Repository Style Analyzer | 78 · Good | CLIFree | ★ 48 | 2mo ago | Rust | Claude Code |
| GraphMind Code Graph | 55 · Major gaps | Desktop appFreemium | ★ 218 | 1mo ago | Rust | Claude Code · Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows restrained privilege design: most tools are read-only analysis; write tools (safe_apply_edit) hit disk only after a verified preview with zero diagnostic delta; Docker runs non-root (uid 65532); HTTP binds 127.0.0.1 by default and recommends env-var tokens over CLI flags; CI verifies sha256 checksums for jdtls/Kotlin downloads. Deductions: safe_apply_edit auto-writes after its diagnostic gate without explicit user confirmation; external effects (running builds/tests, persistent daemons, init writing configs for many clients) are documented but lack per-action authorization; sensitive-data handling is limited to token guidance; uninstall completeness is only asserted, not verified.
Self-consistent: README, CLAUDE.md and CI badges all say 66 tools / 24 skills / 33 languages. Deductions: go.mod contains a 'Dependencies populated by go mod tidy after Wave 1 agents run' comment, hinting generated dependency state and a build-reliability concern; failure-message evidence is strong (phase-violation errors with recovery guidance, 'no identifier found' remediation steps, troubleshooting for indexing and daemon issues) but nothing was executed, so conservatively 2; dependency availability is supported by doctor, timeouts and spawn logs, yet version drift against external language servers (typescript@6 constraint, rust-analyzer re-baselining noted in CI comments) cannot be statically confirmed.
Audience and scenarios are clear (agentic codegen, large-scale refactoring, CI tooling); skill descriptions carry 'Use when' conditions and decision tables, giving decent trigger precision. Boundaries are stated ('Not an LSP server', Caveats sections, dead-code results framed as candidates needing manual review). Deductions: concurrency audit explicitly relies on heuristic source-pattern detection (file truncated at the Caveats section); environment fit spans platforms and Docker but a Windows broker bug existed until v0.12.0, and CI comments confirm language-server baseline drift risk.
Information architecture is excellent: layered README → getting-started → guide/reference docs, install notes covering curl/brew/npm/go/pip/Docker/Scoop/winget with a doctor verification step, complete MIT LICENSE with per-skill license fields and a named author. Deductions: no CHANGELOG in the packet; version info is scattered (v0.12.0 fix appears only inside troubleshooting), so versioning_changelog gets 1; known limitations exist as skill Caveats and CI comments but are not systematic; some referenced docs (e.g. token-savings.md) are not present in the packet for cross-checking.
Output usability is good: GCF is one env var away from JSON, decision tables are structured, phase enforcement blocks invalid tool order. Marginal value is real — collapsing 20+ sequential LSP calls into blast_radius/simulate_edit is semantic capability grep cannot match. Deductions: token-saving figures (5-34x, 92.7%) come from the repo's own experiment script without independent verification; absolute claims like '100% LLM comprehension on every frontier model' exceed what static review can verify; 66 tools add selection/context cost for agents and no negative cost data is offered.
Core engineering claims are traceable: the CI workflow file genuinely lists per-language server installs and tests with pinned versions and checksums, and README/CLAUDE.md/CI corroborate the 66/24/33 numbers. Deductions: facts and marketing are interleaved — the four 'What agents say' AI testimonials are unverifiable and unsourced, GCF benchmark figures point to an external site (gcformat.com) that cannot be cross-checked against repo evidence, and fact/inference separation is weak (score 1); static review cannot run key-path reproduction, hence low overall confidence.
- Publisher is unverified by the FollowAgents registry; identity is unknown. Download badges, AI-agent testimonials and GCF benchmark figures in the README are unverified marketing — re-check before adoption.
- Write tools such as safe_apply_edit write to disk automatically once the diagnostic gate passes, without asking the user; in production prefer the /lsp-safe-edit preview-confirm flow or operate under version control.
- agent-lsp init writes config files for multiple AI clients and installs skill rules, and install.sh uses a curl|sh pattern; review the script and init behavior before running.
- go.mod contains a 'Wave 1 agents run' auto-generation comment, so build/dependency state may be incomplete; when exposing HTTP mode on 0.0.0.0, always set AGENT_LSP_TOKEN.
- This is a static source review with low confidence; the 66-tools/33-language CI-verification claim and token-savings figures were not execution-verified.
FAQ
Does it cost money or need API keys?
Which AI clients are supported?
Why is the first use slow?
What if a tool call fails?
agent-lsp doctor to probe each configured language server and report capabilities. Phase violations return an error with specific recovery guidance plus a JSON copy of the same fields, not a silent failure.How do I use it in CI or remotely?
AGENT_LSP_TOKEN=secret agent-lsp --http --port 8080. Docker images run as non-root (uid 65532) by default and the token should be set via environment variable, never --token on the command line.Is agent-lsp open source?
Is agent-lsp safe to use?
Is agent-lsp still maintained?
Who makes agent-lsp?
What is agent-lsp's official website?
Thanks — we use this to improve the page.