sagefs.nvim

Neovim frontend for SageFs — a live F# development server that eliminates the edit-build-run cycle. SageFs provides sub-second hot reload, live unit testing with a three-speed pipeline, FCS-based code coverage, an affordance-driven MCP server for AI agents, multi-session management, file watching, and more. This plugin connects Neovim to the running daemon, giving you cell evaluation with inline results, session management, hot reload controls, live test state, coverage gutter signs, and SSE live updates from your editor.

Screenshots & Demos

<table> <tr> <td align="center" width="50%">

Eval Loop — evaluate F# cells and see results inline as ghost text

</td> <td align="center" width="50%">

Live Testing — tests run automatically as you type, results in the gutter

</td> </tr> <tr> <td align="center" width="50%">

Coverage — line-level coverage with branch annotations in the gutter

</td> <td align="center" width="50%">

Cell Styles — Full/Normal/Minimal density modes for different workflows

</td> </tr> </table>

Feature Tour

What is SageFs?

SageFs is a .NET global tool that turns F# Interactive into a full development environment. Start the daemon once (sagefs --proj YourApp.fsproj), then connect from VS Code, Neovim, the terminal, a GPU-rendered GUI, a web dashboard, or all of them at once — they all share the same live session state.

Key SageFs capabilities:

• Sub-second hot reload — Save a .fs file and your running web server picks up the change in ~100ms (design target; the engine README cites 300–800ms typical on the current FSI-driven hot path). Harmony patches method pointers at runtime — no restart, no rebuild (SageFs.Core/Middleware/HotReloading.fs). Browsers auto-refresh via SSE/DevReload (SageFs.Host/DevReloadInjector.fs).
• Live unit testing — A three-speed pipeline (design-goal timings ~50ms detect / ~350ms analyze / ~500ms execute): tree-sitter detects tests even in broken code, F# Compiler Service type-checks and builds a dependency graph, then affected tests execute. Gutter markers show pass/fail inline. Covers xUnit, xUnit v3, NUnit, MSTest, TUnit, and Expecto via the executors in LiveTestingExecutors.fs. Configurable run policies per test category. Free — no VS Enterprise license needed.
• FCS-based coverage + IL branch coverage — Line-level code coverage computed from F# Compiler Service typed AST symbol graph (lightweight, no IL instrumentation for basic coverage), plus IL-instrumented branch-level coverage (SageFs.Core/Features/CoverageInstrumenter.fs). Both streamed as SSE events with per-file and per-line annotations.
• Full project context in the REPL — All NuGet packages, project references, and namespaces loaded automatically. No #r directives.
• Affordance-driven MCP — AI tools (Copilot, Claude, etc.) can execute F# code, type-check, explore .NET APIs, run tests, and manage sessions against your real project via Model Context Protocol. The MCP server only presents tools valid for the current session state (SageFs.Core/Affordances.fs) — agents see get_fsi_status during warmup, then send_fsharp_code once ready. No wasted tokens from guessing.
• Multi-session isolation — Run multiple FSI sessions simultaneously across different projects, each in an isolated worker sub-process. A standby pool of pre-warmed sessions makes hard resets near-instant.
• Crash-proof supervisor — Erlang-style auto-restart with exponential backoff (sagefs --supervised, implemented in SageFs/Program.fs). Watchdog state exposed via API and shown in editor status bars.
• Binary session persistence — Session state and test caches saved to compact binary files (.sagefs v3, .sagetc v1) for near-instant cold starts. Raw binary with CRC-32C integrity checking — no JSON parsing, no database (SageFs.Core/Features/TestCachePersistence.fs).

See the SageFs README for full details, including CLI reference, per-directory config (.SageFs/config.fsx), startup profiles, and the full frontend feature matrix.

Plugin Status

This plugin provides the Neovim integration layer. 60 Lua modules under lua/sagefs/ (61 under lua/), 1546 passing tests (1480 busted + 66 headless-Neovim integration) as of the latest run, 53 user commands.

New in Latest

• Telescope source-jump — Press <CR> on any test in the telescope picker to jump directly to its source file and line
• Failure narrative floating window — Press <C-d> on a failing test to see a detailed floating window with:
  • Summary: What happened and why
  • Time since last pass: How long ago this test was green
  • Causal changes: Which symbols/files changed that likely caused the failure
• test_source_locations SSE — Daemon pushes test→file/line mappings for instant navigation
• failure_narratives SSE — Daemon pushes enriched failure context for each failing test

Fully Implemented & Tested

| Feature | Description | |---------|-------------| | Cell evaluation | ;; boundaries define cells. <Alt-Enter> evaluates the cell under cursor. | | Eval and advance | <Shift-Alt-Enter> evaluates and jumps to the next cell. | | Visual selection eval | Select code in visual mode, <Alt-Enter> to evaluate. | | File evaluation | Evaluate the entire buffer with :SageFsEvalFile. | | Cancel evaluation | :SageFsCancel stops a running evaluation. | | Inline results | Success/error output as virtual text at the ;; boundary. | | Virtual lines | Multi-line output rendered below the ;; boundary. | | Gutter signs | Check/X/spinner indicators for cell state (success/error/running). | | CodeLens-style markers | Eval virtual text above idle/stale cells. | | Stale detection | Editing a cell marks its result as stale automatically. | | Flash animation | Brief highlight flash when a cell begins evaluation. | | Session management | Create, switch, stop sessions via picker (:SageFsSessions). | | Project config helper | :SageFsConfig creates or opens .SageFs/config.fsx so you can disable warmup auto-open. | | Project discovery | Auto-discovers .fsproj files and offers to create sessions. | | Smart eval | If no session exists, prompts to create one before evaluating. | | Session context | Floating window showing assemblies, namespaces, warmup details. | | Hot reload controls | Per-file toggle, watch-all, unwatch-all via picker. | | SSE dispatch pipeline | All SageFs event types classified and routed through pcall-protected dispatch. | | SSE live updates | Subscribes to SageFs event stream with exponential backoff reconnect (1s→32s). | | State recovery | Full state synced on SSE reconnect — no stale data after drops. | | Live diagnostics | F# errors/warnings streamed via SSE into vim.diagnostic. | | Check on save | BufWritePost sends .fsx file content for type-checking (LSP already covers .fs). Diagnostics arrive via SSE. Behind check_on_save config flag. | | Live test gutter signs | Pass/fail/running/stale signs per test in the sign column. | | Live test panel | :SageFsTestPanel → persistent split with test results, <CR> to jump to source. | | Tests for current file | :SageFsTestsHere → floating window with tests for the file you're editing. | | Run tests | :SageFsRunTests [pattern] → trigger test execution with optional filter. | | Test policy controls | :SageFsTestPolicy → drill-down vim.ui.select for category+policy. | | Enable/disable live testing | :SageFsEnableTesting / :SageFsDisableTesting → explicit live test pipeline control. | | Test trace | :SageFsTestTrace → floating window showing the three-speed pipeline state. | | Coverage gutter signs | Green=covered, Red=uncovered per-line signs from FCS symbol graph. | | Coverage panel | :SageFsCoverage → floating window with per-file breakdown + total. | | Coverage statusline | Coverage percentage in combined statusline component. | | Type explorer | :SageFsTypeExplorer → completions-based namespace/type drill-down. | | History browser | :SageFsHistory → eval history for the cell under cursor with snapshot preview. | | Export to .fsx | :SageFsExport → export session history as executable F# script. | | Load script | :SageFsLoadScript → load an .fsx file via #load. File completion support. | | Call graph | :SageFsCallers/:SageFsCallees → floating window with call graph. | | Daemon lifecycle | :SageFsStart/:SageFsStop → start/stop the SageFs daemon from Neovim. | | Status dashboard | :SageFsStatus → floating window with daemon, session, tests, coverage, config. | | User autocmd events | 37 event types fired via User autocmds for scripting integration. | | Combined statusline | require("sagefs").statusline() → session │ testing │ coverage │ daemon. | | Code completion | Omnifunc-based completions via SageFs completion endpoint. | | Session reset | Soft reset and hard reset with rebuild. | | Treesitter cell detection | Structural ;; detection filtering boundaries in strings/comments. | | SSE session scoping | Events tagged with SessionId — only your active session's data renders. Multi-session safe. | | Branch coverage gutters | Three-state gutter signs from IL probe data: ▐ green (full), ◐ yellow (partial), ▌ red (uncovered). Color-blind accessible (shape+color pairing). | | Branch EOL text | Optional n/m branches annotation at end of line for partial coverage. Behind density preset. | | Filterable test panel | Test panel filters by scope: b = binding (treesitter), f = current file, m = module, a = all, Tab = cycle. Failures sorted first. | | Display density presets | <leader>rD cycles minimal (signs only) → normal (signs+codelens+inline) → full (everything+branch EOL). | | Cell highlight styles | ╭│╰ bracket in sign column (normal), ▎ bar (minimal), line highlight (full). No opaque backgrounds on transparent terminals. | | Treesitter scope inference | Fil