Local semantic navigation for wiki-first agentic workflows

mi-lsp helps AI agents navigate real software projects.

Give them a map before they act.

A local navigation layer for codebases, docs and wiki-first workflows. mi-lsp helps humans and agents find canonical context without turning the whole repo into a giant prompt.

Install in one command View on GitHub Read the notes
local-first CLI-first evidence-first no MCP required
repo evidence pack 
$ irm https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install-agent.ps1 | iex
$ mi-lsp init . --name myapp
$ mi-lsp nav ask "where does checkout validation happen?" --workspace myapp --format toon
Installed from GitHub Releases:

latest: v0.4.1
checksums: verified
workers: installed

Found the checkout validation path:

1. Canonical spec
   .docs/wiki/05-requisitos.md#RF-CHECKOUT-003

2. Main implementation
   src/checkout/validateOrder.ts

3. Nearby tests
   tests/checkout/validateOrder.test.ts
Next: mi-lsp nav pack "change checkout validation" --workspace myapp --format toon
docs code tests trace
Quick install

Install the CLI and the agent skill in one command.

The installer pulls the latest GitHub Release, selects the host package, verifies SHA256 checksums, installs the bundled workers, and runs the first health checks.

latest: v0.4.1 Windows + Linux SHA256 verified bundled workers

Recommended for Codex and Claude-style workflows: install mi-lsp, then register the mi-lsp skill so agents know how to use the local repo map before reading files.

macOS release assets are not published yet. The Linux shell installer exits clearly on Darwin instead of guessing.

Agent install CLI + skill

# Windows PowerShell
irm https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install-agent.ps1 | iex

# Linux shell
curl -fsSL https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install-agent.sh | sh

First minute from any repo

mi-lsp init . --name myapp
mi-lsp nav ask "how is this workspace organized?" --workspace myapp --format toon
mi-lsp nav pack "understand how authentication works" --workspace myapp --format toon
Problem

Giving an agent a repo is not giving it context.

Most coding agents start every task cold. In a real project, code, canonical docs, decisions, tests, scripts, raw notes and obsolete material all live together. Without navigation, the agent confuses signal with noise.

mi-lsp gives them the missing layer: repo-native context.

grep auth old docs? generated file unrelated test maybe service?
Agents start cold. Many times, a full repo is not context. It is a maze.
Docscanon
Symbolscode
Servicesroutes
Testsproof
Agent Packsmall context
Docs → Code → Tests → Agent Pack bounded, local, traceable
Solution

An operational map between repo canon and agent work.

mi-lsp connects canonical docs, source files, symbols, services, tests and requirements into small, useful context packs. It does not replace the wiki or technical judgment. It reduces the cost of finding the right context.

Docs and project rules Symbols, services and routes Requirements, tests and traceability Agent-ready reading packs
Workflow

From vague task to bounded context.

Route the task before reading the repo. Give agents the smallest useful context, then trace what changed.

01

Connect

mi-lsp init . --name myapp

Register the workspace and detect how the repo is organized.

02

Map

mi-lsp nav workspace-map

Inspect the indexed shape of docs, code and project structure.

03

Ask

mi-lsp nav ask "how does login work?"

Route a natural-language task to the right docs and files.

04

Pack

mi-lsp nav pack "implement magic link login"

Create the smallest useful reading set for an agent.

05

Read

mi-lsp nav multi-read file.cs:1-80

Expand only the file slices that the reading pack actually needs.

Before / After

Less blind grep. More bounded context.

Before mi-lsp

The agent searches broadly, reads too much, and returns a plausible answer with weak evidence.

Agent:
  "I'll search for auth..."

Reads:
  37 files
  9 outdated docs
  4 generated files
  2 unrelated tests

Result:
  Plausible change, weak evidence.

After mi-lsp

The agent starts from canonical docs, relevant implementation, and nearby tests - with a smaller context window and a clearer validation path.

Agent:
  "I'll route this through mi-lsp first..."

Reads:
  canonical auth spec
  login service
  auth middleware
  nearby tests

Result:
  Smaller context, stronger evidence.
Built for agents

Works with the agents you already use.

Codex Claude Code Hermes OpenCode shell scripts CI jobs

mi-lsp is CLI-first and local-first. Use it from agents, scripts or CI without turning your repository into somebody else's platform.

Safety

Context first. Changes second.

local-first CLI-first no implicit commits no hidden patching no vendor lock-in docs-first worktree-aware audit-ready

mi-lsp does not need to own your workflow. It does not commit, push, patch or hide changes. It gives agents better context so your existing workflow stays in control.

Commands

Install fast, then ask for the repo map.

The public path is already concrete: install from the latest release, register a workspace, ask for orientation, then request a bounded reading pack.

Install for agents recommended

# Windows PowerShell
irm https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install-agent.ps1 | iex

# Linux shell
curl -fsSL https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install-agent.sh | sh

CLI-only install/update

# Windows PowerShell
irm https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install.ps1 | iex

# Linux shell
curl -fsSL https://raw.githubusercontent.com/fgpaz/mi-lsp/main/scripts/install/install.sh | sh

Daily loop works today

mi-lsp init . --name myapp
mi-lsp nav ask "where does checkout validation happen?" --workspace myapp --format toon
mi-lsp nav pack "change checkout validation" --workspace myapp --format toon
mi-lsp nav multi-read path/to/file.cs:1-90 path/to/test.ts:20-80 --workspace myapp --format toon
Part of TEDI

One open-source layer in a larger human-agent workflow.

TEDI is the broader direction: workflows where humans and agents work with canon, contracts, workers and evidence. mi-lsp is the navigation/context layer: the map that helps agents find the right material before they execute.

navigation memory canon workers evidence

The landing keeps the promise honest: mi-lsp is available as a focused open-source project. The rest of TEDI is the build-in-public path around wiki-first agentic engineering.

Start here

Agents need a map before they act.

Install mi-lsp View on GitHub Read the Wiki-First notes 
mi-lsp init . --name myapp
mi-lsp nav ask "where should I start?" --workspace myapp --format toon
mi-lsp nav pack "understand this task" --workspace myapp --format toon