SageFs — VS Code Extension

Save your F# file → tests run → results appear inline — all in < 500ms.

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

✨ What You Get

Note: This extension is not yet published on the VS Marketplace. See Installing below.

🚀 Quick Start

1. Install SageFs CLI: dotnet tool install --global SageFs
2. Install this extension: Download .vsix from Releases → Extensions sidebar → ... → Install from VSIX
3. Open an F# project in VS Code
4. Press Alt+Enter on any expression — the daemon starts automatically and results appear inline

That's it. Live testing enables automatically when Expecto tests are detected.

⌨️ 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

Gutter Icons

Coverage Bars (left gutter)

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 dashboard.

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 gutter bars — Per-line coverage health (AllPassing / SomeFailing / NoCoverage) shown in the gutter
• 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
• Call graph viewer — Visualize test dependency graphs
• 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

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
• 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
• 7 custom theme colors — Inline result colors respect your VS Code theme

Requirements

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

Installing

The SageFs VS Code extension is not published on the VS Marketplace yet. Install manually:

Option A: Download from GitHub Releases (recommended)

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 B: 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

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 appearing in gutter

1. Your project needs Expecto tests (not xUnit/NUnit)
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.