mi-lsp
A local CLI that answers "where is X" and "what does the spec say" without an agent burning its context window to find out.
Agents and developers repeat the same costly loop: grep, open a whole file, skim it, and grep again without knowing what is canonical. mi-lsp replaces that with a repo-local index that finds relevant code, reads exact file ranges, and follows canonical documentation. It works from the terminal, through Claude Code/Codex skills, or through the optional local stdio MCP door; the CLI remains the authority and does not require a long-running server.
Who it's for: developers navigating an unfamiliar or large repository, and coding agents that need reliable, bounded, token-cheap navigation instead of a heavyweight always-on server.
Quickstart · Core concepts · Which command do I use? · Releases
Quickstart in 5 minutes
1. Install. The recommended installer adds the CLI and the mi-lsp skill for Claude Code and Codex. It requires npx.
irm https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install-agent.ps1 | iex
curl -fsSL https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install-agent.sh | sh
Want only the CLI (no skill)? Use install.ps1 / install.sh instead:
irm https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install.ps1 | iex
curl -fsSL https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install.sh | sh
The installer picks the right bundle for win-x64, win-arm64, linux-x64, linux-arm64, darwin-x64, or darwin-arm64, verifies its SHA256 checksum, and keeps the bundled worker beside the CLI.
For maintainers installing a build from a checkout, use pwsh ./scripts/release/install-local.ps1 -Rid win-arm64 on Windows ARM64, or sh ./scripts/release/install-local.sh --rid linux-arm64 / --rid osx-arm64 on the matching Linux/macOS host. These local installers build and install the CLI plus its worker bundle; they are separate from the public download installers. scripts/release.sh X.Y.Z builds the six release bundles under dist/ without publishing or installing them. Its --upload mode publishes only when tag vX.Y.Z already points at HEAD.
2. Initialize your repo. This detects the workspace, registers an alias, and starts indexing.
mi-lsp init . --name myapp
For very large workspaces, indexing can smart-sync degrade to the background on its own (or you can force it with --background); poll it with mi-lsp index status <job-id> before your first query. Use --wait to force a full inline sync instead.
3. Ask for what you actually want, in plain language. nav intent is the goal-shaped entry point — it classifies your question and routes to code or to canonical docs automatically:
mi-lsp nav intent "how does the daemon start" --workspace myapp --format toon
A real run against this repository returns a bounded preview with the matching docs, a score, and — critically — a next_queries list telling you exactly what to run next instead of leaving you to guess:
backend: intent
items[5]:
- doc_id: RF-GPH-010
doc_path: .docs/wiki/05_requirements/RF-GPH-010.md
next_queries[2]: mi-lsp nav search RF-GPH-010 --include-content --workspace myapp,"mi-lsp nav multi-read .docs/wiki/05_requirements/RF-GPH-010.md:1-120 --workspace myapp"
score: 108
title: RF-GPH-010 - ...
mode: docs
next_hint: rerun with --full for expanded detail
ok: true
workspace: myapp
Follow the emitted next_queries / continuation.next verbatim rather than improvising a broader search.
4. Read only the exact ranges you need, never a whole file:
mi-lsp nav search "billing retry" --include-content --workspace myapp --format toon
mi-lsp nav multi-read src/billing/retry.go:20-80 tests/billing/retry_test.go:10-55 --workspace myapp --format toon
The query and paths above are illustrative; use whatever your own search returns. multi-read batches several file ranges into one call — no separate "open file" round-trip per result. Rust repositories are detected from Cargo.toml (including Cargo workspaces) and indexed for catalog/search navigation.
Core concepts
| Concept | What it means |
|---|
| Workspace | A repo (or a parent folder holding several independent repos — a "container" workspace) registered under an alias. mi-lsp workspace which reports the resolved alias, root, and the executable in use, without mutating anything. |
| Index | A repo-local SQLite catalog (.mi-lsp/index.db) of symbols, files, and the wiki graph. Built by init/index; queried directly without a daemon. |
| Daemon (optional) | A per-user background process that keeps semantic workers (Roslyn, tsserver, gopls, pyright, rust-analyzer) warm across terminals and agents for lower-latency queries. If it is down or stale, cheap reads (search, multi-read, wiki search) still work directly against the index; deeper semantic surfaces fall back visibly instead of failing silently. |
| Wiki / canon navigation | nav wiki * treats a repo's canonical documentation (RS/RF/FL/TP/CT/TECH/DB) as authority. nav ask/nav pack/nav route rank canonical docs first and use code only as supporting evidence. |
| TOON format and budgets | --format toon is the recommended default output format — smaller than JSON, easy to parse (key: value scalars, key[N]{cols}: arrays). --token-budget and --max-chars (global; 0 = unset) bound how much comes back; truncation always leaves continuation.next and a truncation marker instead of silently dropping content. |
| Continuation | Most envelopes carry a continuation block. Prefer continuation.next over improvising a wider query. |
| The four fallback reason codes | A terminal external failure carries exactly one reason_code — unsupported_operation, unavailable_binary, invalid_workspace, or explicit_incomplete — plus a separate, sanitized detail. A timeout, silence, or an unlabeled "done" is not one of these and is not a license to switch to / silently. |
Which command do I use?
| I want to... | Run |
|---|
| Understand a goal without knowing the exact command | mi-lsp nav intent "<goal>" --workspace <alias> --format toon |
| Find a symbol by name | mi-lsp nav find <symbol> --workspace <alias> --format toon |
| Search text and see matching code inline | mi-lsp nav search "<pattern>" --include-content --workspace <alias> --format toon |
| Read one or more exact file ranges | mi-lsp nav multi-read file1:10-60 file2:1-40 --workspace <alias> --format toon |
| See what a change affects (callers, tests, docs) | mi-lsp nav affected <path> --include-tests --include-docs --workspace <alias> --format toon |
| Understand one symbol fully (definition, callers, implementors, tests) | mi-lsp nav related <symbol> --workspace <alias> --format toon |
| Navigate the wiki / governance docs (RS/RF/FL/TP/CT/TECH/DB) | mi-lsp nav wiki search "<topic>" --layer RF,FL,TP,CT --workspace <alias> --format toon |
| Get the cheapest canonical anchor doc (no index needed) | mi-lsp nav route "<task>" --workspace <alias> --format toon |
nav.find and nav.multi-read check only their candidate or explicit paths before reading published data, with a 250 ms request budget; nav.affected checks explicit impact paths with a 1 s budget. nav.route and nav.intent can refresh up to five Markdown candidates within 500 ms, then reload and rerank once only after a successful commit. A failed refresh preserves the available query result and reports the limitation. These scoped refreshes update catalog/document records, not graph generations; a stale graph may require a full reindex. They run synchronously without background writes or Roslyn extraction.
When output is consumed by an agent (for example, when stdout is not a terminal or MI_LSP_CLIENT_NAME is set), navigation uses a compact agent response by default. It reports the selected workspace first and limits find, search, and multi-read to five results. Successful responses omit coach and governance blocks; use --verbose for more detail. An explicit --format json|toon|yaml|compact always selects that format and preserves its existing response shape.
Using it from agents and hosts
The CLI is the authority — every door below is a thin, optional layer over the same nav commands, and none of them add their own cache, index, or background worker.
- Agent skill. Installing the skill (via
install-agent) gives Claude Code and Codex a mi-lsp skill describing the command surface; see skills/mi-lsp/SKILL.md and the longer quickstart reference.
- No MCP door. The local stdio
mi-lsp mcp door was removed (2026-10-15). Agents call the CLI directly; hosts that need MCP go through mi-mcp / sandinas-mcp, which run the mi-lsp CLI per tool call. See the retired MCP adapter note.
- Per-host integrations under
integrations/ (each optional, none required):
- Claude Code (
integrations/claude-code) — a plugin with advisory UserPromptSubmit/PostToolUse hooks that call mi-lsp nav suggest. Hooks fail open: a missing binary, timeout, or bad JSON just means no suggestion, never a blocked turn.
- Codex (
integrations/codex) — a config.toml snippet that sets MI_LSP_CLIENT_NAME; no server registration.
MI_LSP_BIN. When set, it must point at the real executable — mi-lsp.exe on Windows, mi-lsp elsewhere. A .cmd/.bat shim is not the product and is not a valid override; hosts that spawn without a shell (including the Claude Code hooks) cannot execute a shim at all.
Performance and footprint
Measured on 2026-09-24 against this repository; see .docs/wiki/_retired/technical/TECH-MCP-ADAPTER.md for the full note and caveats.
| Surface | Measured | Caveat |
|---|
Warm nav overview (daemon already warm) | p50 ≈ 232 ms, p95 ≈ 374 ms, over 20 timed calls | Not strictly comparable to an older baseline (p50 ≈ 4.7 s) from a different client binary against the same long-running daemon; the payload size of that baseline was never archived, so the comparison is directional at best. |
These are workflow numbers on one sample, not a universal benchmark — results depend on your repository, query, and daemon warm-state.
Troubleshooting
daemon status warns the executable is stale (its hash doesn't match this CLI build). Run mi-lsp daemon restart before trusting daemon-backed results; direct/cheap reads keep working regardless.- A large first index returns a
job_id. Use mi-lsp init --background to return immediately, then poll with mi-lsp index status <job-id> before querying that workspace.
- "workspace not found" / ambiguous workspace. Run
mi-lsp workspace which --format toon to see the resolved alias, root, and executable without mutating anything; mi-lsp workspace list --group-by-root --format toon and mi-lsp workspace doctor --format toon diagnose duplicate roots and stale paths.
- Windows
.cmd shim. If mi-lsp on PATH resolves to a .cmd/.bat shim instead of the real mi-lsp.exe, host doors that spawn without a shell (Claude Code hooks) will fail to launch it. Point MI_LSP_BIN, or the host's command field, at the real executable.
More detail: TROUBLESHOOTING.md.
Learn more
Compatibility and limits
Public release bundles cover Windows (win-x64, win-arm64), Linux (linux-x64, linux-arm64), and macOS (darwin-x64, darwin-arm64). Source builds are documented in CONTRIBUTING.md. The commands above describe the repository's supported release/install targets; they do not claim a runtime smoke on every RID for each change.
- C# gets the deepest semantics, through a bundled Roslyn worker. TypeScript/JavaScript and Python use local catalogs with optional
tsserver/pyright-langserver enrichment. Go uses a native AST catalog with optional gopls enrichment; Rust uses a lexical catalog with optional rust-analyzer references/context. These backends do not claim Roslyn-level semantics.
- No semantic editing or automated refactoring, no remote or multi-host daemon sharing, no authenticated remote governance UI.
- Every door under
integrations/ is optional; the CLI is never a second product waiting behind them.
License
MIT
