docs(#189): document ENABLE_LSP_TOOL + per-language LSP plugin install by atlas-apex · Pull Request #193 · me2resh/apexyard

atlas-apex · 2026-05-09T06:35:43Z

Summary

Add an "Optional: LSP-aware code navigation" section to docs/getting-started.md covering the cost-benefit (~3-15× cheaper on shallow semantic queries per the Phase 1 spike numbers), the two-piece opt-in (ENABLE_LSP_TOOL=1 env var + per-language plugin), per-language install notes for TypeScript / Python / Go / Rust, and the caveats (cold-start latency, cross-project queries still need grep).
Add an LSP row to the Quick Reference table in CLAUDE.md.
Add an "LSP-aware skills inside a workspace" subsection to the daily-workflow area of docs/multi-project.md noting the transparent fallback to grep when LSP is absent.
Pure docs — no hooks / skills / settings touched. Closes [Docs] Document ENABLE_LSP_TOOL opt-in + per-language plugin install #189.

Plugin marketplace links: deliberately point at the Claude Code plugins documentation and tell readers to search the marketplace UI by language. Per the ticket's risk note, individual plugin URLs in the new ecosystem aren't yet stable enough to pin from a framework doc — better to link the search than rot a deep link.

Testing

Open docs/getting-started.md and verify the new "Optional: LSP-aware code navigation" section reads end-to-end without dangling references — the cost-benefit, the two-piece opt-in, four per-language install blocks, and four caveats.
Open CLAUDE.md Quick Reference and confirm the LSP row appears at the bottom of the table.
Open docs/multi-project.md and search for "LSP-aware skills inside a workspace" — the new subsection sits between the apexyard status CLI briefing and the "Upgrades — pulling from upstream" section.
Run gh issue view 189 --repo me2resh/apexyard and tick off the four AC bullets against the diff.
(Optional, can't be automated here) On a workstation with an installed LSP plugin and ENABLE_LSP_TOOL=1, run /code-review against a small TS PR and confirm the latency / token cost matches the section's claim.

Glossary

Term	Definition
LSP	Language Server Protocol — a JSON-RPC interface that lets a language-specific server answer semantic queries (definition, references, hover, diagnostics) about source code
LSP server	The language-specific binary (`tsserver`, `pyright`, `gopls`, `rust-analyzer`, …) that implements LSP over stdio for a given source tree
`ENABLE_LSP_TOOL`	Environment variable (singular `_TOOL`, not plural) that enables Claude Code's built-in LSP tool — off by default since v2.0.74
Plugin (Claude Code)	A self-contained marketplace-installed directory that ships skills, agents, hooks, MCP servers, or LSP servers wired in via `.lsp.json`
`tsserver`	The TypeScript language server, bundled with the `typescript` npm package — typically already present in any TypeScript project's `node_modules`
`pyright`	A Microsoft-maintained Python type-checker that doubles as an LSP server; installable via npm or as a project devDependency
`gopls`	The official Go language server, installed via `go install golang.org/x/tools/gopls@latest`
`rust-analyzer`	The de-facto Rust LSP server, ships as a `rustup` component on most modern toolchains
Shallow vs multi-hop semantic query	Shallow: single symbol → single location lookup (definition, references). Multi-hop: chain across modules to summarise behaviour. LSP's input-token win is large on shallow queries, modest on multi-hop
Cold-start latency	The first-query indexing cost a language server pays when it opens a project — sub-second on small libraries, 30-90s on a Go monorepo or large Rust workspace

… install - Add "Optional: LSP-aware code navigation" section to docs/getting-started.md covering the cost-benefit (~3-15× cheaper on shallow semantic queries per the Phase 1 spike numbers), the two-piece opt-in (env var + plugin), and the caveats (cold-start latency, cross-project queries still grep). - Per-language install notes for TypeScript (tsserver), Python (pyright), Go (gopls), Rust (rust-analyzer). Marketplace links left as searches — individual plugin URLs are not yet stable enough to pin. - Add LSP row to the Quick Reference table in CLAUDE.md. - Add "LSP-aware skills inside a workspace" subsection to the daily-workflow area of docs/multi-project.md noting the transparent fallback to grep. Pure docs — no code changes. Closes #189

atlas-apex

Code Review: PR #193

Commit: 525591dd6038d66ecdbdb3bca28d8a82e4656ae5

Summary

Pure docs PR adding the optional LSP-aware code-navigation path (Claude Code v2.0.74+, ENABLE_LSP_TOOL=1 + per-language plugin). +108 lines across docs/getting-started.md (new section), CLAUDE.md (Quick Reference row), docs/multi-project.md (workspace-level note + cross-project caveat). No code, hooks, skills, or settings touched.

Checklist Results

Architecture & Design: N/A (docs-only)
Code Quality: Pass
Testing: N/A (docs-only)
Security: Pass — no secrets, no private project names, no pinned third-party plugin URLs
Performance: N/A
PR Description & Glossary: Pass — Summary, Testing, Glossary all present; glossary has 10 entries including the explicit _TOOL singular note
Technical Decisions (AgDR):N/A — pure documentation of an existing upstream feature, no new decisions introduced

Issues Found

None.

Verification against ticket #189 risk notes

All four cost-benefit caveats present in docs/getting-started.md § Caveats:
- Cold-start latency (30-90s on Go monorepos / large Rust workspaces / huge TS projects) ✓
- Cross-project portfolio queries still need grep ✓
- Transparent fallback to grep when LSP absent — "no new failure mode" ✓
- Marketplace link flux — explicit "links may move" caveat ✓
Per-language install blocks — all four with binary install + verification command:
- TypeScript: npx tsserver --version / npm ls typescript
- Python: npm install -g pyright (+ uv / pip alternatives)
- Go: go install golang.org/x/tools/gopls@latest (+ Go 1.21 + go.mod requirement)
- Rust: rustup component add rust-analyzer (+ rustup.rs link, which is a stable upstream)
ENABLE_LSP_TOOL named exactly — singular _TOOL everywhere in the diff (verified via grep). Glossary explicitly disambiguates: "singular _TOOL, not plural". Known papercut handled.
Marketplace links don't pin specific plugin URLs — links go to the general plugins doc and instruct readers to search the marketplace UI. Inline guidance reinforces this in the caveats: prefer language-community-maintained over third-party. Only stable upstream URL is rustup.rs for the Rust toolchain itself, which is appropriate.
No private project names in new content — verified.
markdownlint-cli2 CI — pass. Pre-existing MD060 noise in CLAUDE.md (unrelated) not added to.
CI — all three checks green (Verify Ticket ID, lychee, markdownlint-cli2).
PR body — Summary (4 bullets), Testing (5 steps incl. an honest "can't be automated here" note for the live LSP run), Glossary (10 entries).

Suggestions

None blocking. Optional polish for a future iteration:

The tsserver install block has the verification command but the comment "Install the Claude Code plugin from the marketplace" with no command — symmetrical to the others, just noting it for consistency. Not worth blocking on.
Consider adding a small "Disable" subsection (unset ENABLE_LSP_TOOL) for completeness; readers who want to A/B the cost will look for it. Trivial follow-up.

Verdict

APPROVED (posted as comment — GitHub blocks self-approval)

The risks called out in #189 — env var name papercut, marketplace link rot, missing fallback caveat — are all handled. The cost-benefit numbers come from the actual Phase 1 spike (PR #184 / ticket #178) rather than vendor marketing. Glossary is one of the better ones I've reviewed for an apexyard PR — it pre-empts the "_TOOL vs _TOOLS" question explicitly.

Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: 525591dd6038d66ecdbdb3bca28d8a82e4656ae5

… install (#193) - Add "Optional: LSP-aware code navigation" section to docs/getting-started.md covering the cost-benefit (~3-15× cheaper on shallow semantic queries per the Phase 1 spike numbers), the two-piece opt-in (env var + plugin), and the caveats (cold-start latency, cross-project queries still grep). - Per-language install notes for TypeScript (tsserver), Python (pyright), Go (gopls), Rust (rust-analyzer). Marketplace links left as searches — individual plugin URLs are not yet stable enough to pin. - Add LSP row to the Quick Reference table in CLAUDE.md. - Add "LSP-aware skills inside a workspace" subsection to the daily-workflow area of docs/multi-project.md noting the transparent fallback to grep. Pure docs — no code changes. Closes #189 Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>

github-actions Bot added github-issue has-ticket labels May 9, 2026

atlas-apex commented May 9, 2026

View reviewed changes

atlas-apex merged commit 2128350 into dev May 9, 2026
3 checks passed

atlas-apex deleted the docs/GH-189-lsp-env-docs branch May 9, 2026 06:57

This was referenced May 9, 2026

[Docs] Document ENABLE_LSP_TOOL opt-in + per-language plugin install #189

Closed

[Feature] /setup enables LSP by default — install language server + env var + plugin in one flow #208

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(#189): document ENABLE_LSP_TOOL + per-language LSP plugin install#193

docs(#189): document ENABLE_LSP_TOOL + per-language LSP plugin install#193
atlas-apex merged 1 commit into
devfrom
docs/GH-189-lsp-env-docs

atlas-apex commented May 9, 2026

Uh oh!

atlas-apex left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

atlas-apex commented May 9, 2026

Summary

Testing

Glossary

Uh oh!

atlas-apex left a comment

Choose a reason for hiding this comment

Code Review: PR #193

Summary

Checklist Results

Issues Found

Verification against ticket #189 risk notes

Suggestions

Verdict

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants