msnav — cross-service Ruby navigation

Cross-service go to definition, find references, hover docs, and CodeLens jumps for Ruby microservice workspaces — the navigation a single-repo language server cannot do: from the HTTP call in one service to the route that serves it in another, from a route to the handler it's wired to, from a RabbitMQ publish to its consumer. Works in plain workspaces and in per-service dev containers, where jumps land in the window that owns the target service.

The extension is a thin client of the msnav daemon (a Ruby server over a coderag index) and manages it ruby-lsp style: it starts the daemon itself on activation and shows its state in the status bar.

Requirements

1. The msnav gem, available on PATH in the environment where you edit (the dev container image, or your machine for local windows):

   gem install msnav
   

   In a dev container, bake it into the image (RUN gem install msnav).

   Note: unlike ruby-lsp, do not add msnav to your application's Gemfile. It never loads your app's code — it reads the shared index database — and a github:-sourced Gemfile entry produces a binstub that cannot run outside bundle exec.

2. An indexed hub. The index is built once on the host with coderag:

   cd /path/to/workspace     # the folder containing all services
   coderag index . --no-embed
   

3. Dev containers only: the shared data-dir mount — one line in devcontainer.json, identical for every service of every hub (the SQLite index stays on the host):

   "mounts": [
     "source=${localEnv:HOME}/.local/share/coderag,target=/root/.local/share/coderag,type=bind"
   ]
   

Ruby ≥ 2.6 for the daemon; VS Code ≥ 1.80 or Cursor.

Getting started

1. Install this extension and the msnav gem (above).
2. Index the hub on the host (above).
3. Open a service and any Ruby file — the extension probes the daemon and, when nothing answers, runs msnav up (idempotent: a healthy daemon, including a Python coderag one, always short-circuits the spawn). The status bar shows the state: msnav ✓ healthy, msnav ⚠ serves another hub, msnav ✗ down. Click it to retry; details live in the msnav output channel.

No settings are needed in the standard flows: the daemon finds its hub through the data-dir mount (matching your folder by name, then by file contents — anonymous mounts like /app work), and the container↔host path mapping is derived from the daemon's reported scope.

Features

• Go to Definition / Implementation (F12) — an HTTP call site jumps to the route in the target service; a route line jumps to the handler class it routes to (through DI indirection); a publish jumps to the consumer's handler. Results merge with ruby-lsp's own.
• Find References (⇧F12) — on a route line: every call site in other services that hits this endpoint.
• Hover — the target endpoint's YARD @return documentation, shown on the calling line.
• CodeLens (bridge mode) — ↗ GET /users/:id [users-service] links on every cross-service call site. Clicking opens the target where it already lives: this window, another window (routed via the shared registry — works across dev containers), or a new host window opened on the service folder at the exact line.
• Daemon lifecycle — autostart on activation, health in the status bar, msnav doctor for diagnostics.

Modes (msnav.mode)

Settings

Commands

Troubleshooting

• Status bar msnav ✗ / exit code 2 — run msnav doctor in the (container) terminal: it walks the hub-resolution ladder and prints what each step found, with fixes.
• msnav ⚠ — the daemon on the port serves a different hub; use another port or stop it (msnav down).
• The msnav output channel logs every autostart attempt, registration, and routed open.
• More (Bundler contexts, git-gem pitfalls, non-root containers): troubleshooting in the repo README.