SageFs: VS Code Extension

Live eval, live testing, coverage and hot reload all run today, each with limits that are written down. The main README and docs/ say what is solid and what isn't.

SageFs brings live evaluation, instant test feedback, and coverage visualization to VS Code. No configuration needed. Just press Alt+Enter.

✨ What You Get

Available on the VS Code Marketplace and Open VSX.

🚀 Quick Start

1. Install SageFs CLI: dotnet tool install --global SageFs
2. Install this extension: Search SageFs in the Extensions sidebar, or code --install-extension willehrendreich.sagefs
3. Open an F# project in VS Code
4. Press Alt+Enter on any expression, the daemon starts automatically and results appear inline

Live testing is a per-session toggle. If you pick the Live Testing workflow (SageFs: Switch Workflow) it is turned on for you once the session is ready. In the other workflows, run SageFs: Enable Live Testing once your test session is loaded.

⌨️ Keybindings

💡 All keybindings are scoped to F# files only. Shift+Enter is deactivated when a notebook is focused to avoid conflicts with Jupyter.

🎨 Understanding What You See

Test marks

The extension draws these as text after the end of the test's line, and as a tick in the scrollbar's overview ruler. It puts no icon in the gutter. The only gutter icon you see is VS Code's own run and debug glyph from the Test Explorer.

Coverage marks (in front of the code)

These are text drawn before the first character of the line, not gutter icons.

The per-line health view draws a │ in the same three colors instead of ▸ and ○.

Inline Decorations

💡 Hover over any decoration for more details, including failure narratives with causal analysis.

Status Bar

The status bar (bottom of VS Code) shows three items:

Click the daemon status item to open the session menu.

The daemon item's tooltip is also its accessible name. It reads SageFs: MyProject [Hot Reload] - session 7c8bec06 - 4 session(s), so it names the workflow and which session this window is talking to. The test summary item's accessible name is its headline only, and the tooltip adds what the last run was and why, each on its own line.

The hot reload item

After a save in a Hot Reload session, the item shows the daemon's verdict for that save, and I show one message when the save is settled:

The tooltip has the daemon's message, the mechanism, and, when a patch left the REPL behind the running app, that it is behind by N saves. Hard Reset (Rebuild) brings the REPL level, and it stops the running app, so the message offers it as a button and does not do it for you. Clicking the item opens the Output channel, where the same text is written.

Features

Code Evaluation

• Alt+Enter: Evaluate the current selection or ;;-delimited code block. Results appear as inline decorations.
• Alt+Shift+Enter: Evaluate the entire file
• Shift+Enter: Evaluate current block and advance cursor to the next
• Ctrl+Alt+Enter: Evaluate all ;; blocks in the file
• CodeLens: Clickable "▶ Eval" buttons above every ;; block
• Density cycling: Toggle between Full / Normal / Minimal inline result display

Live Unit Testing

• Inline test decorations: ✓/✗/● markers on test lines, updated in real-time via SSE
• Native Test Explorer: Tests appear in VS Code's built-in Test Explorer via a TestController adapter
• Test result CodeLens: "✓ Passed" / "✗ Failed" above every test function
• Failure diagnostics: Failed tests appear as native VS Code squiggles
• Coverage marks: Per-line coverage health (AllPassing / SomeFailing / NoCoverage) drawn as text in front of the line
• Inline failure details, ⊘ markers with Expected/Actual diffs, exception messages, and timeouts
• Failure narratives: Enriched failure context: summary, time since last pass, causal changes
• Test source locations: Test Explorer items automatically link to their source file and line
• Test policy controls: Enable/disable live testing, run all tests, or configure run policies from the command palette
• Tests covering a symbol: pick a symbol and list the tests that cover it, for the session this window shows
• Test trace: Browse test cycle events

Live Diagnostics

• F# type errors and warnings stream in via SSE as you edit, appearing as native VS Code squiggles

Hot Reload

• Hot Reload sidebar: Tree view in the activity bar showing all project files with per-file and per-directory watch toggles
• Toggle individual files, directories, or watch/unwatch everything at once

Scrub a running value

• Value knob: Hold the modifier your editor.multiCursorModifier names (Alt by default) and drag across a number to scrub it: one column of drag is one step, and whole numbers step by one while decimals step in their last place. The literal keeps the file's style, so hex stays hex.
• The write goes through the daemon's nudge_value tool rather than the file, which is what gives it the dashboard knob's rules for free: the write is journaled, checked against the seen hash the inspect returned, refused with what moved if the source changed underneath, and rolled back if the new text does not type-check.
• The honest limit, because the gesture is a workaround. VS Code's extension API never reports that a modifier is held, TextEditorSelectionChangeEvent carries no modifiers, and there are no editor mouse events at all. What the API does report is what an Alt+click creates: with multiCursorModifier = "alt" (the default) it adds a cursor, so a mouse-driven selection change carrying more than one selection is the only way that state arrives. Set editor.multiCursorModifier to something else and the knob does not engage, by design rather than by bug.

Session Management

• Session Context sidebar: Loaded assemblies, opened namespaces, failed opens, warmup details
• Sessions sidebar: View all sessions with inline switch/stop/reset actions
• Multi-session: Create, switch, and manage multiple sessions from the command palette

Which session a window uses

One daemon serves every window and every agent on the machine, so a window has to know which session is its own. I decide it like this:

1. The session you picked with Switch Session, or that Create Session just made, for as long as it exists.
2. Otherwise the first session whose working directory is inside one of the folders you have open.
3. Otherwise none. The status bar says none of the daemon's sessions is for this workspace, and the views offer Create Session. I do not borrow a session because it happens to be first in the daemon's list.

Create Session finds the session it made, selects it, and tells you. If it cannot tell which one is new, it says so and asks you to pick it, and does not guess. Every command that acts on the session carries its id: live testing on, off and run, run one test, load script, and the Test Explorer run button. Reset, hard reset, cancel and run policy have no session id on the daemon's routes, so for those I make the window's session the daemon's active one first, and the command does not run if that switch fails.

Each row in the Sessions sidebar reads <project names> <id> · active · this workspace · Ready · 3 evals · Work/molina. The short id comes first because the sidebar cuts the text from the right. active is the session this window uses, this workspace is any session started in a folder you have open, and the last two folders of the working directory follow. More than two projects show as the first two and +N more. The tooltip has everything.

Other agents' events

The daemon sends every session's events to every window. By default I show only the ones about this window's session, a session started in this workspace, or a file under this workspace: a session fault, and the File reloaded lines in the Output channel. Another agent's fault does not pop up in your window. The Output channel notes the ones I left out at the debug log level. Turn on sagefs.showEventsFromAllSessions to see everything.

A session fault message is one sentence and a remedy. The daemon's full diagnosis goes to the Output channel, and the message's Show Output button opens it.

• Export session: Save current session state as a .fsx script
• Session menu: Quick-access menu for all session operations

More

• Type Explorer sidebar: Browse .NET types and namespaces interactively from the activity bar
• Event history: Browse recent pipeline events via QuickPick
• FSI bindings browser: View all current FSI bindings
• Dashboard webview: Open the SageFs dashboard directly inside VS Code
• Status bar: Active project, eval count, test summary, eval performance sparkline. Click to open dashboard.
• Auto-start: Detects .fsproj/.sln/.slnx files and offers to start SageFs automatically
• Ionide integration: Hijacks Ionide's FSI: Send Selection commands so Alt+Enter routes through SageFs
• 11 custom theme colors: Inline result and test mark colors respect your VS Code theme (the list is under contributes.colors in package.json)

Requirements

• SageFs installed as a .NET global tool (dotnet tool install --global SageFs)
• An F# project (.fsproj or .sln) in your workspace

Installing

Option A: VS Code Marketplace (recommended)

Search for SageFs in the Extensions sidebar, or install from the command line:

code --install-extension willehrendreich.sagefs

Also available on Open VSX for VSCodium and other compatible editors.

Option B: Download from GitHub Releases

Each GitHub Release includes a .vsix file:

code --install-extension sagefs-<version>.vsix

Or: open the Extensions sidebar → click ... (top-right) → "Install from VSIX..." → select the downloaded file.

Option C: Build from source

cd sagefs-vscode
npm install
npm run compile
npx @vscode/vsce package
code --install-extension sagefs-*.vsix

Settings

Commands

Evaluation

Daemon & Session

The Sessions sidebar also has inline per-row actions (Switch To, Stop, Reset), click the icons on a session row instead of going through the command palette.

Hot Reload

Live Testing

Sidebar Views

🔧 Troubleshooting

"SageFs: offline" in status bar

The daemon isn't running. Fix:

1. Run dotnet tool install --global SageFs if you haven't installed the CLI
2. Click the status bar item, or run Command Palette → "SageFs: Start Daemon"
3. The extension auto-starts the daemon when it detects F# projects: if this isn't happening, check sagefs.autoStart is true

No inline results after Alt+Enter

1. Check the Output panel (View → Output → select "SageFs" from the dropdown) for errors
2. Verify the daemon is running: the status bar should show ⚡ SageFs: YourProject
3. Try restarting: Command Palette → "SageFs: Hard Reset (Rebuild)"
4. Make sure your cursor is in an F# file (keybindings only activate for fsharp language)

Tests not getting marks

1. SageFs discovers Expecto, xUnit (including v3), NUnit, MSTest, and TUnit tests. Expecto is the best-covered path today, so start there if you can.
2. Enable live testing: Command Palette → "SageFs: Enable Live Testing"
3. Check that the daemon discovered tests: status bar should show a test count (e.g., 🧪 42/42 ✓)
4. Check the Output panel for errors

Status bar shows no connection

The SSE connection to the daemon dropped. It will reconnect automatically. If it persists:

1. Check if the daemon process is still running (look for SageFs in your task manager)
2. Restart the daemon: Command Palette → "SageFs: Restart Daemon"
3. Check Output panel (select "SageFs") for connection errors

"No .fsproj or .sln found"

Open a folder containing an F# project. The extension auto-detects projects. For non-standard layouts, set sagefs.projectPath in VS Code settings to the explicit path.

Daemon crashes or restarts unexpectedly

The extension detects daemon crashes and shows a restart prompt. If it keeps crashing:

1. Check the SageFs output in your terminal for stack traces
2. Try starting SageFs manually from a terminal: SageFs
3. File an issue at github.com/WillEhrendreich/SageFs/issues

Architecture

This extension is written entirely in F# using Fable, no TypeScript. The F# source compiles to JavaScript, giving you type-safe extension code with the same language as your project.

Key architectural decisions:

• SSE (Server-Sent Events) for all real-time data: test results, diagnostics, coverage, eval results
• POST commands for all actions: eval, reset, start/stop: responses are acknowledgments only
• Native VS Code APIs via Fable bindings: TestController, CodeLens, TreeView, Diagnostics, Decorations

Development

cd sagefs-vscode
npm install
npm run compile

Press F5 in VS Code to launch the Extension Development Host.