loupe

Open the code locations an AI cites — file:line, ranges, many at once — in a Neovide window: distinct files as tabs, every location in a quickfix list, the current range highlighted. Navigate by key or click. Cross-platform (macOS, Windows, Linux), driven over Neovim's RPC (no fragile keystroke injection).

loupe src/main.cpp:23 src/main.cpp:88 src/util.cpp:10-24

→ opens main.cpp and util.cpp as tabs, lists all three locations in a quickfix pane, highlights main.cpp:23. Step through them with the keys below or from the terminal.

Status: macOS is verified end-to-end. Windows and Linux are implemented but still being verified — they're available on the @next prerelease tag (npm i -g @boomarche/loupe@next). The stable latest tag will land once Windows is confirmed.

Install

npm install -g @boomarche/loupe

You also need Neovim and Neovide on PATH (loupe detects them and prints the right hint if missing):

• macOS: brew install neovim && brew install --cask neovide
• Windows: winget install Neovim.Neovim && winget install Neovide.Neovide
• Linux: your package manager / the Neovide release AppImage

loupe never auto-installs anything.

Usage

loupe <ref> [<ref> ...]   # open locations: file, file:line, file:line:col, file:start-end
loupe next                # step to the next location (highlight + tab follow)
loupe prev                # step to the previous location
loupe list                # focus the quickfix pane and print the list

Refs resolve relative to the current directory. Colons and spaces in paths are safe. A missing file is skipped with a warning; all-missing is an error.

In-editor keys

| Action | macOS | Windows / Linux | |---|---|---| | Next / previous location | Cmd ↓ / Cmd ↑ (or Ctrl) | Ctrl ↓ / Ctrl ↑ (or Alt) | | Jump to a file's tab | Cmd 1…Cmd 9 (or Ctrl) | Ctrl 1…9 (or Alt) | | Zoom in / out / reset | Cmd = / Cmd - / Cmd 0 (or Ctrl) | Ctrl = / Ctrl - / Ctrl 0 (or Alt) | | Step (Neovim-native) | ]q / [q | ]q / [q | | Jump to a quickfix entry | Enter or double-click | Enter or double-click |

The shortcut bar is shown as a header on the quickfix pane.

Per-session windows

Each Claude Code session gets its own Neovide window, keyed on $CLAUDE_SESSION_ID and titled loupe: <short-id>, so concurrent sessions never share a window. A plain terminal uses a shared default window. Override the key with LOUPE_SESSION=<name>.

The window is loupe-managed (a display surface): running loupe <refs> again resets its tabs, so don't rely on it for unsaved manual edits.

Use it with Claude Code

Add to your CLAUDE.md so the agent surfaces locations as it cites them:

When you cite concrete code locations (file:line / file:start-end), also run loupe <all the refs> in one call so I can see them. Navigate yourself with the keys above, or ask me to loupe next / prev while explaining.

Environment

• LOUPE_SESSION=<key> — override the per-session window key.
• LOUPE_DRY_RUN=1 — print the Neovim commands instead of running them (used in tests).

Develop

npm install
npm run build
npm test          # unit (refs/session parsing, dry-run command contract)
npm run test:int  # headless-nvim integration (quickfix, highlight, switchbuf, isolation)

State lives under ~/.local/state/loupe/<session>/ (macOS/Linux) or %LOCALAPPDATA%\loupe\<session>\ (Windows). loupe drives Neovim via nvim --server <addr> --remote-expr "v:lua.Loupe.*" — the editor runs the code, nothing is "typed," so there's no keystroke-injection class of bug.