mi-lsp

README

mi-lsp

harness_protocol: SDD-HARNESS-v1
id: "README"
kind: "support-doc"
audience: "dual"
imports:
  - '[[00_gobierno_documental]]'
  - '[[README]]'
exports:
  - 'README'
agent_must_read:
  - .docs/wiki/00_gobierno_documental.md
  - README.md
agent_may_edit:
  - README.md
agent_must_not_edit:
  - .docs/wiki/_mi-lsp/read-model.toml
verify:
  - mi-lsp nav governance --workspace mi-lsp --format toon
  - mi-lsp nav wiki validate-harness --workspace mi-lsp --format toon
stop_if:
  - governance_blocked=true
  - harness_verdict=BLOCKED
evidence:
  - README.md

Semantic code navigation for coding agents, without requiring MCP.

mi-lsp is a local CLI for exploring large .NET/C# + TypeScript codebases from the terminal. It keeps a lightweight repo-local index, supports optional warm state through a daemon, and now includes a docs-first entrypoint for onboarding a repo fast. For onboarding and discovery, AXI is now selective by default on the surfaces where it saves the most tokens; use --classic when you want the old CLI behavior and --axi when you want to force AXI on a classic surface.

Quick Start

1. Install

The recommended install path is a bundled release from GitHub Releases.

1. Download the asset for your platform (win-x64, win-arm64, linux-x64, or linux-arm64) from the Releases page.
2. Extract it and keep workers/<rid>/ next to the mi-lsp binary.
3. Run the binary directly or add it to your PATH.

Sanity check:

mi-lsp version
mi-lsp info
mi-lsp worker status --format compact

If you move the binary after extraction, run mi-lsp worker install once to copy the bundled worker into ~/.mi-lsp/workers/<rid>/. Regular C# queries resolve the Roslyn worker by layout presence in bundle -> installed -> dev-local order, while mi-lsp worker status is the explicit compatibility probe. mi-lsp version --format toon exposes the exact executable path, SHA256, Go runtime, OS/architecture, protocol version, RID, and VCS metadata without needing a registered workspace or daemon. worker status keeps the same visible diagnostic payload whether it is served directly or through the daemon; only active_workers changes with live state. It now also surfaces cli_path and protocol_version, which makes stale or unexpected binaries on PATH easier to diagnose. On Windows, non-interactive child processes are started hidden so normal queries should not open extra console windows. Maintainers use the AE release distribution gate for binary refreshes: pwsh ./scripts/release/ae-release-binaries.ps1 -Clean builds all four RIDs and refreshes the current host install; add -Publish -Tag <vX.Y.Z> only after the clean release tag is ready.

2. Initialize a workspace

The shortest first-run path is:

mi-lsp init . --name myapp

That command:

• detects the workspace shape
• registers it in ~/.mi-lsp/registry.toml
• writes .mi-lsp/project.toml
• indexes code and docs by default
• leaves you with a ready --workspace myapp

If you prefer the explicit workflow, workspace add still exists:

mi-lsp workspace add C:\code\my-dotnet-app --name myapp
mi-lsp workspace status myapp --format compact

AXI discovery starts from the root command by default:

mi-lsp
mi-lsp workspace status myapp

3. Ask one useful question first

mi-lsp nav ask "how is this workspace organized?" --workspace myapp

nav ask is docs-first:

• it prioritizes .docs/wiki when the repo has one
• it uses explicit traceability links before text heuristics
• it adds code evidence so you can jump into the implementation immediately

When you want the reading order instead of a prose answer:

mi-lsp nav pack "understand how this login flow works" --workspace myapp
mi-lsp nav pack "understand how this login flow works" --workspace myapp --full

4. Use the right command for the job

You want to...	Run this
Understand the repo quickly	mi-lsp nav ask "how is this workspace organized?" --workspace myapp
Get the canonical docs reading order for a task	mi-lsp nav pack "understand how billing retry works" --workspace myapp
See the high-level map of services	mi-lsp nav workspace-map --workspace myapp --axi
Understand one symbol deeply	mi-lsp nav related MySymbol --workspace myapp --format compact
Read the code around one line	mi-lsp nav context path/to/file.cs 42 --workspace myapp --format compact
Search text and see the matching code	mi-lsp nav search "billing retry" --include-content --workspace myapp
Find a wiki note by meaning (multilingual)	mi-lsp nav recall "<query>" --workspace myapp
Choose the cheapest safe evidence reentry path	mi-lsp nav evidence inventory "AE evidence lifecycle" --workspace myapp --format toon
Search symbols by intent	mi-lsp nav intent "password reset frontend" --workspace myapp --repo web
Audit one backend/service path	mi-lsp nav service src/backend/orders --workspace myapp --format compact
Read several files in one call	mi-lsp nav multi-read file1.cs:1-80 file2.ts:20-80 --workspace myapp --format compact

Use --full when an AXI preview asks you to expand detail:

mi-lsp nav search "billing retry" --include-content --workspace myapp --full
mi-lsp nav workspace-map --workspace myapp --axi --full

5. Parent folder with several repos

Start broad, then narrow semantic queries:

mi-lsp nav workspace-map --workspace myapp --format compact
mi-lsp nav search OrderHandler --workspace myapp --format compact
mi-lsp nav search "forgot password" --workspace myapp --repo web --format compact
mi-lsp nav refs IOrderRepository --workspace myapp --repo Orders.Api --format compact

Docs-First Search

If the repo has .docs/wiki, mi-lsp nav ask uses it as the primary source of truth. The project can optionally add .docs/wiki/_mi-lsp/read-model.toml to teach mi-lsp how to rank:

• functional docs (01-06)
• technical docs (07-09)
• UX/UI docs (10-16)
• generic fallback docs (README*, docs/, .docs/)

That gives you a local, explainable answer instead of a black-box summary.

Semantic Recall Over Knowledge Wikis

For repositories that have a markdown knowledge wiki but no formal 00_gobierno_documental.md, use mi-lsp nav recall to embed a freeform query and rank wiki sections by semantic similarity. It works multilingually: a Spanish query will find matching English notes by meaning, not just text. Offline ⇒ lexical fallback: when embeddings service is unavailable, recall degrades gracefully to keyword search.

The feature is gated by optional [embeddings] configuration in .mi-lsp/project.toml. A block with both base_url and model is active by default; set enabled = false only when you need an explicit local kill switch:

[embeddings]
# enabled = false  # optional kill switch; omit for normal active config
provider = "openai"
base_url = "http://localhost:8000/v1"
model = "bge-m3"
dim = 1024
api_key_env = "MI_LSP_EMBEDDINGS_API_KEY"
profile = "knowledge-wiki"
batch_size = 100
timeout_ms = 30000

The API key is populated via mkey run and injected as an environment variable (MI_LSP_EMBEDDINGS_API_KEY), never committed to the repo. tesla bge-m3 is the documented reference endpoint (1024-dim multilingual embeddings). The knowledge-wiki profile auto-detects when no formal governance exists, bypassing the spec-driven gate. Chunks are stored in repo-local wiki_chunk_embeddings table with incremental re-embedding by content hash. Rerunning mi-lsp index can backfill missing vectors even when the document catalog reports no source changes.

Evidence Inventory For Agent Reentry

Use mi-lsp nav evidence inventory "<query>" --workspace myapp --format toon before opening large audit folders or historical prompts. The preview returns canonical wiki anchors first, then metadata-only summaries for .docs/auditoria, .docs/raw/prompts, and .docs/raw/plans. It prefers manifest.yaml, verdict.md, issues.yaml, summaries, assertions, and hashes before raw turns, logs, screenshots, or prompt bodies. Heavy raw evidence is counted with file/byte/token estimates and omitted from content by default.

Use With Claude Code, Codex, and Skill-Based Agents

The repository ships a ready-to-install skill in skills/mi-lsp. If your coding tool supports folder-based skills, copy or symlink that folder into the skill directory your tool scans.

Typical installs:

# Codex
New-Item -ItemType Directory -Force $HOME\.codex\skills | Out-Null
Copy-Item -Recurse .\skills\mi-lsp $HOME\.codex\skills\

# Claude Code or any runner using a folder-based skills setup
New-Item -ItemType Directory -Force $HOME\.agents\skills | Out-Null
Copy-Item -Recurse .\skills\mi-lsp $HOME\.agents\skills\

Once the skill is installed, an agent can start with prompts such as:

Use $mi-lsp to initialize this repo and explain how it is organized.
Use $mi-lsp to answer where daemon routing is documented and which code backs it.
Use $mi-lsp to audit src/backend/orders and summarize endpoints, consumers, publishers, and entities.
Use $mi-lsp to read the relevant files for OrderHandler and show only the important slices.

For session-wide AXI discovery defaults:

$env:MI_LSP_AXI = "1"

To opt out on an AXI-default surface:

mi-lsp --classic
mi-lsp nav search "billing retry" --workspace myapp --classic --format compact

For shared daemon attribution across several agents, set:

$env:MI_LSP_CLIENT_NAME = "codex"
$env:MI_LSP_SESSION_ID = "demo-session"

Workspace Model

mi-lsp supports two canonical workspace shapes:

• single: one repo with one obvious semantic root
• container: one parent folder that contains many independent repos without requiring a parent .sln

Recommended operating pattern:

• use the parent folder for broad discovery: ask, find, search, overview, workspace-map
• use the child repo or explicit selectors for deep semantics: refs, context, deps
• use service for evidence-first exploration of an implementation area

Runtime Model

• One global daemon per OS user, shared across terminals, Claude Code, Codex, and local subagents
• One live runtime per (workspace_root, backend_type, entrypoint_id) inside the daemon
• Repo-local semantic state:
  • .mi-lsp/project.toml
  • .mi-lsp/index.db
• Global local-machine state:
  • ~/.mi-lsp/registry.toml
  • ~/.mi-lsp/daemon/state.json
  • ~/.mi-lsp/daemon/daemon.db

The daemon is a performance optimization, not a prerequisite for the CLI.

Core Capabilities

mi-lsp init [path] [--name <alias>] [--no-index]
mi-lsp workspace add|remove|scan|list|warm|status
mi-lsp nav ask|pack|symbols|find|refs|overview|outline|service|search|context|deps|multi-read|batch|related|workspace-map|diff-context|recall
mi-lsp index [path] [--clean]
mi-lsp info
mi-lsp daemon start|stop|restart|status|logs
mi-lsp worker install|status
mi-lsp admin open|status|export

Useful global flags:

--workspace
--axi
--classic
--full
--format compact|json|text|toon|yaml
--client-name
--session-id
--backend roslyn|tsserver|catalog|text
--no-auto-daemon
--compress

Build From Source

Source builds are intended for contributors and maintainers.

Prerequisites:

• Go 1.24+
• .NET 10 SDK

Build and test:

make build
make test
make lint

For release-like local validation on a specific RID:

pwsh ./scripts/release/build-dist.ps1 -Rids @('win-x64') -Clean
pwsh ./scripts/release/install-local.ps1 -Rid win-x64 -InstallDir $HOME\bin

For AE-managed release distribution across Windows/Linux and ARM64/x64:

pwsh ./scripts/release/ae-release-binaries.ps1 -Clean
pwsh ./scripts/release/ae-release-binaries.ps1 -Clean -MirrorRoot C:\repos\buho\assets\skills\mi-lsp
pwsh ./scripts/release/ae-release-binaries.ps1 -Clean -Publish -Tag vX.Y.Z

The -Publish mode requires a clean worktree and a tag that points at HEAD; pushing the tag triggers the GitHub release workflow that uploads all platform assets.

Troubleshooting

Common first checks:

mi-lsp info
mi-lsp worker status --format compact
mi-lsp workspace status myapp --format compact
mi-lsp nav ask "how is this workspace organized?" --workspace myapp

If a repo changed heavily under .docs/wiki, rerun:

mi-lsp index --workspace myapp --clean

If a command fails before mi-lsp itself starts, treat it as a host incident first. See the public runbook in TROUBLESHOOTING.md.

Current v0.1.0 Scope

• Global daemon with governance UI and local telemetry
• Repo-local lightweight catalog in SQLite with repo ownership and docs graph
• Semantic C# queries via Roslyn worker
• Container workspaces with explicit or inferred repo/entrypoint routing
• TS/JS discovery index for symbols, routes, and overview
• Optional TS semantic bridge through tsserver
• Optional Python semantic bridge through pyright-langserver
• Service exploration summaries via nav service
• Docs-first repo questions via nav ask
• Canonical reading packs via nav pack

Out of scope for v0.1.0:

• MCP transport
• Semantic editing/refactors
• Automatic semantic fanout across all child repos
• Remote or multi-host daemon sharing
• Authenticated governance UI
• Additional languages beyond the current C#/TS/Python/Go catalog focus
• Strong completeness scoring for services

Documentation

The versioned documentation canon lives in .docs/wiki/. README.md is the public entrypoint; the repo wiki is the source of truth.

Start here:

• Documentation Governance
• Functional Scope
• Architecture
• Flow Index
• Requirements Index
• Data Model
• Test Matrix
• Technical Baseline
• Physical Data Model
• Technical Contracts
• Troubleshooting

License

MIT