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. Harmony patches method pointers at runtime — no restart, no rebuild. Browsers auto-refresh via SSE.
• Live unit testing — A three-speed pipeline: tree-sitter detects tests in ~50ms (even in broken code), F# Compiler Service type-checks and builds a dependency graph in ~350ms, then affected tests execute in ~500ms total. Gutter markers show pass/fail inline. Covers xUnit, NUnit, MSTest, TUnit, and Expecto via a two-tier provider system. Configurable run policies per test category (unit tests on every keystroke, integration on save, browser on demand). 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 showing which branches within a line are hit. 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 — 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). 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.

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. 37 Lua modules, 1160 tests, zero failures.

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 | 28 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 | Files without ;; use treesitter to find the top-level declaration under cursor. Two-mode: explicit (;;) or inferred (cursor context). | | Runtime statistics | :SageFsStats → eval count, average latency, SSE events, reconnects, cells tracked. | | Eval timeline | :SageFsTimeline → flame-chart visualization of eval history with latency breakdown. | | Diff viewer | :SageFsDiff → side-by-side diff of last two evaluations of the current cell. | | Dependency arrows | :SageFsArrows → cross-cell dependency visualization in floating window. | | Scope map | :SageFsScopeMap → binding scope map showing what's defined in each cell. | | Type flow | :SageFsTypeFlow → cross-cell type flow visualization showing how types propagate. | | Notebook export | :SageFsNotebook [markdown\|fsx] → export session as literate notebook. | | Playground | :SageFsPlayground → open scratch F# buffer for quick experiments. | | Health module | :checkhealth sagefs validates CLI, plugin, daemon, treesitter, curl. |

Requirements

• SageFs running (sagefs --proj YourApp.fsproj)
• Neovim 0.10+
• curl o