SageFs 0.6.195

<div align="center">

SageFs

You save. Tests pass. Browser updates. Under a second.

A live F# engine — hot reload, live testing, AI-native — for every editor, for free.

</div>

What is SageFs?

SageFs is a live F# development engine. Start it once, connect any editor — VS Code, Neovim, Visual Studio, or the built-in TUI — and get sub-500ms feedback on every save: inline results, live test markers, hot reload, and AI agent access via MCP. It runs as a daemon with isolated session workers, so multiple editors and AI agents can share the same live state simultaneously.

How is SageFs different from Ionide? Ionide provides IntelliSense, diagnostics, and project support through the F# Compiler Service. SageFs adds live execution: eval any expression and see results inline, continuous test feedback on every save, and hot reload that patches your running app. Use both together — Ionide for editing, SageFs for running.

Platforms: Windows, macOS, Linux. Requires .NET 10 SDK.

Status: Active development. Used in production by the author.

Table of Contents

• Three Things That Change Everything
• Get Started
• Two Workflows: REPL vs Live
• Mental Model
• What You Get in Each Editor
• Keybindings
• Gutter Icons
• The $3,000/year Feature — Free
• Under the Hood
• Coming from Another Language?
• Visual Demos
• Contributing
• License

🆕 Never written F#? You're in the right place.

Pick your language — each guide maps familiar concepts to F#, with runnable examples that show results the instant you press Alt+Enter.

🐍 Python · 📓 Jupyter · 🔷 C# · ☕ Java · 🟨 JS/TS · 🦀 Rust · 🧘 F# Koans

Or just dive in: dotnet tool install --global SageFs && sagefs — then open any .fsx file and hit Alt+Enter.

---

Three Things That Change Everything

⚡ Hot Reload — Save and It's Live

Save a .fs file. SageFs reloads it in ~100ms via Harmony runtime patching. No rebuild. No restart. Connected browsers auto-refresh via SSE. Your web app is already showing the new code before your fingers leave the keyboard.

🤖 AI-Native — Your Agent Can Compile

SageFs exposes a Model Context Protocol server with an affordance-driven state machine — AI agents only see tools valid for the current session state. No wasted tokens guessing. Copilot, Claude, and any MCP client can execute F# code, type-check, explore .NET APIs, and run tests against your real project.

🖥️ One Daemon, Every Editor — Simultaneously

Start SageFs once. Connect from VS Code, Neovim, Visual Studio, a terminal TUI, a GPU-rendered Raylib GUI, a web dashboard, or an AI agent. Open them all at the same time — they share the same live session. Switch editors without switching tools.

graph TB
    D[SageFs Daemon]

    D --- VS[VS Code]
    D --- NV[Neovim]
    D --- VI[Visual Studio]
    D --- TU[Terminal TUI]
    D --- GU[Raylib GUI]
    D --- WB[Web Dashboard]
    D --- AI[AI Agents]
    D --- JP[Jupyter Kernel]

    style D fill:#1a1b26,stroke:#7aa2f7,stroke-width:2px,color:#c0caf5
    style VS fill:#1a1b26,stroke:#9ece6a,color:#c0caf5
    style NV fill:#1a1b26,stroke:#9ece6a,color:#c0caf5
    style VI fill:#1a1b26,stroke:#9ece6a,color:#c0caf5
    style TU fill:#1a1b26,stroke:#bb9af7,color:#c0caf5
    style GU fill:#1a1b26,stroke:#bb9af7,color:#c0caf5
    style WB fill:#1a1b26,stroke:#7dcfff,color:#c0caf5
    style AI fill:#1a1b26,stroke:#e0af68,color:#c0caf5
    style JP fill:#1a1b26,stroke:#bb9af7,color:#c0caf5

---

Get Started

1. Install SageFs (30 seconds)

Prerequisites: .NET 10 SDK. That's it.

dotnet tool install --global SageFs

2. Check your environment (optional)

sagefs check

Validates .NET SDK, FSI, project files, port availability, and daemon state. Actionable hints on every failure. Skip this if you've used SageFs before.

3. Start the daemon

sagefs

SageFs opens an interactive terminal. Then create a session for YourProject.fsproj from your editor, MCP client, or the dashboard.

No project? Just run sagefs with no arguments — the daemon starts bare and waits for clients. Your editor will create sessions on demand.

4. Connect your editor

VS Code — Install SageFs from the VS Code Marketplace, open an F# file, press Alt+Enter on any expression. Result appears inline in < 500ms.

Neovim — Add "WillEhrendreich/sagefs.nvim" to your plugin manager. Press Alt+Enter to evaluate. See Neovim setup.

Visual Studio 2022 — Install SageFs from the Visual Studio Marketplace. Press Alt+Enter. The daemon starts automatically.

Terminal only — sagefs tui for the built-in terminal UI (powered by SageTUI Elm Architecture), or sagefs gui for the Raylib GPU window. Use sagefs tui --legacy-tui for the classic imperative renderer.

5. Enable live testing

⚠️ Work in progress — live testing is functional but still being stabilized. You may encounter rough edges, especially around session switching and test discovery timing. We're actively improving it.

Save any file → tests run automatically → green/red gutter markers appear. No configuration needed — SageFs discovers Expecto tests and runs them on every save.

6. What you'll see

• Gutter markers: ✓ green (passing), ✗ red (failing), ○ gray (no coverage)
• Inline results: Expression values appear to the right of your code
• Coverage bars: Colored bars in the gutter show which lines are covered by tests
• Failure details: Hover over red markers to see Expected vs Actual diffs

💡 Tip: Use the SageFs: Mark All Tests Stale command (Command Palette) to re-run everything.

MCP (streamable HTTP):  http://localhost:37749/       ← recommended for new MCP clients
MCP (legacy SSE):       http://localhost:37749/sse    ← older MCP clients
Dashboard:              http://localhost:37750/dashboard

New to F#? You don't need any F# knowledge to start. Jump to the migration guide for your language — each one maps concepts you already know to F#, with runnable examples.

<details> <summary>Build from source</summary>

git clone https://github.com/WillEhrendreich/SageFs.git
cd SageFs
dotnet build && dotnet pack SageFs -o nupkg
dotnet tool install --global SageFs --add-source ./nupkg --no-cache

</details>

📚 Full Documentation — Guides, deep dives, technical reference, and contributor docs.

---

Two Workflows: REPL vs Live

📖 Full guide: Understanding Workflow Modes — decision tree, diagrams, real-world scenarios, troubleshooting, and why live testing isn't a third mode.

SageFs sessions run in one of two modes.The tradeoff is a physical constraint of the .NET runtime — not a SageFs limitation.

REPL mode (default) gives you a full interactive F# session. You can redefine types, experiment freely, and iterate on designs. This is what you want when you're prototyping domain types, exploring APIs, or working through a problem interactively.

Live mode enables browser hot reload — save a .fs file and connected browsers update instantly via SSE, with no manual refresh. To make this work, SageFs uses runtime patching to inject code changes into the running app. That patching requires a single-assembly FSI mode, which means you cannot redefine types (you'll get FS0037 errors). Expressions, function bodies, and let bindings work fine.

	REPL (default)	Live
Type redefinition	✅ Full — redefine types freely	❌ FS0037 — expression-level changes only
Browser hot reload	❌ Manual refresh required	✅ Save → patch → SSE push
Live testing	✅ Full	✅ Full
Best for	Prototyping, domain modeling, exploration	Web apps with Falco, Datastar, ASP.NET

Choosing the right mode

• Building a web app with Falco.Datastar, Giraffe, or any ASP.NET pipeline? Use Live — you want save-and-see-it feedback in the browser.
• Exploring types, designing domain models, writing tests, or working in .fsx scripts? Use REPL — you need the freedom to reshape types as you go.
• Not sure? Start with REPL. Switch to Live when you need browser hot reload.

Switching modes

Use the switch_workflow MCP tool, or your editor's command:

• Neovim: :SageFsWorkflow live or :SageFsWorkflow repl
• VS Code: Command Palette → SageFs: Switch Workflow
• TUI/GUI: Ctrl+W toggles between modes

When you switch, SageFs creates a new session in the target mode and stops the old one. Any REPL-defined bindings are lost — persisted files are unaffected.

Auto-detection

When SageFs detects web-oriented packages in your project (Falco.Datastar, Giraffe, Saturn, etc.), it suggests switching to Live mode. You can accept or dismiss the suggestion.

---

Mental Model — How SageFs Works

SageFs has exactly three concepts: a daemon, sessions, and clients.

graph TB
    subgraph D[SageFs Daemon - one per machine]
        S1[Session Worker 1 - MyApp]
        S2[Session Worker 2 - Tests]
        S3[Session Worker 3 - Bare FSI]
        SVC[MCP / Dashboard / File Watcher / Hot Reload]
    end

    D --- VS[VS Code]
    D --- NV[Neovim]
    D --- TU[Terminal TUI]
    D --- AI[AI Agent - MCP]

    style D fill:#1a1b26,stroke:#7aa2f7,stroke-width:2px,color:#c0caf5
    style S1 fill:#1a1b26,stroke:#9ece6a,color:#c0caf5
    style S2 fill:#1a1b26,stroke:#9ece6a,color:#c0caf5
    style S3 fill:#1a1b26,stroke:#9ece6a,color:#c0caf5
    style SVC fill:#1a1b26,stroke:#e0af68,color:#c0caf5
    style VS fill:#1a1b26,stroke:#bb9af7,color:#c0caf5
    style NV fill:#1a1b26,stroke:#bb9af7,color:#c0caf5
    style TU fill:#1a1b26,stroke:#bb9af7,color:#c0caf5
    style AI fill:#1a1b26,stroke:#bb9af7,color:#c0caf5

The daemon is a service. It starts bare — no project, no session. It just listens. Clients tell it what to do.

Sessions are isolated workers. Each session is a separate OS process with its own FSI instance, its own loaded project, its own file watcher. They can't interfere with each other. Create as many as you need.

Clients are thin. Your editor plugin, the TUI, the Jupyter bridge, or an AI agent — they all connect to the same daemon. They create sessions, send code, read results. Multiple clients can share the same session or each use their own.

The workflow:

1. Start the daemon: sagefs
2. A client (editor, Jupyter, dashboard, AI) creates a session: POST /api/sessions/create with a project path
3. The daemon spawns a worker, loads the project, starts watching files
4. The client sends code, reads diagnostics, runs tests — all through the daemon
5. Other clients can connect to the same session simultaneously

This means the daemon doesn't need to know your project at startup. It starts bare and waits for clients to create or attach to sessions.

---

What You Get in Each Editor

Every frontend connects to the same daemon. Open several at once — they all see the same state.

Capability	VS Code	Neovim	Visual Studio	TUI	Raylib GUI	Web	AI (MCP)
Eval code / file / block	✅	✅	✅	✅	✅	✅	✅
Inline results	✅	✅	✅	✅	✅	✅	✅
Live diagnostics (SSE)	✅	✅	✅	✅	✅	✅	✅
Hot reload toggle	✅	✅	✅	✅	✅	✅	—
Session management	✅	✅	✅	✅	✅	✅	✅
Code completion	✅	✅	✅	✅	✅	✅	✅
CodeLens	✅	✅	✅	—	—	—	—
Live test gutters	✅	✅	✅	✅	✅	—	—
Coverage gutters	✅	✅	✅	✅	✅	—	—
Failure narratives	✅	✅	✅	✅	✅	—	✅
Test source-jump	✅	✅	✅	✅	✅	—	—
Test panel	✅	✅	✅	✅	✅	—	—
Test policy controls	✅	✅	✅	—	—	—	✅
Type explorer	✅	✅	—	—	¹	—	✅
Call graph	✅	✅	—	—	—	—	—
History browser	✅	✅	—	✅	✅	—	—
Test trace	✅	✅	—	—	—	—	✅

¹ Server-side data ready. Editor UI integration pending (VS SDK limitations or work-in-progress).

<details> <summary><strong>Editor setup guides</strong></summary>

VS Code

Install from the VS Code Marketplace, or grab the .vsix from Releases for manual install. Written entirely in F# via Fable — no TypeScript.

Features: Alt+Enter eval, CodeLens, live test decorations, native Test Explorer integration, hot reload sidebar, session context, type explorer, call graph, event history, dashboard webview, status bar, auto-start, Ionide command hijacking, coverage gutter bars, inline failure decorations, failure narrative enrichment, and test source-jump.

Neovim

sagefs.nvim — 59 Lua modules, 1400+ tests, 57 commands.

-- lazy.nvim
{ "WillEhrendreich/sagefs.nvim", ft = { "fsharp" }, opts = { port = 37749, auto_connect = true } }

Features: Cell eval, inline results, gutter signs, SSE live updates, live test panel, coverage panel with per-file breakdown, type explorer, call graph, history browser, session export to .fsx, code completion, branch coverage gutters, filterable test panel, display density presets, combined statusline component, Telescope source-jump (<CR>), failure narrative floating window (<C-d>), and SSE-driven test state caching.

Visual Studio

Install from the Visual Studio Marketplace, or grab the .vsix from Releases. Uses the VisualStudio.Extensibility SDK with F# core logic. Eval, CodeLens, session management, diagnostics, coverage gutter glyphs (CoverageGlyphTagger), test source-jump via TestStateTracker, and inline failure narrative context.

The VS extension includes kill switches for individual features. See the VS Extension README for details.

AI Agent (MCP)

SageFs exposes dozens of MCP tools — from send_fsharp_code to run_tests to discover_features. Any MCP client can connect. See the full MCP Tools Reference for the complete list and per-client config examples.

Streamable HTTP (recommended — auto-reconnects, no session drops):

{ "mcpServers": { "sagefs": { "type": "streamable-http", "url": "http://localhost:37749/" } } }

SSE (legacy clients that don't support Streamable HTTP yet):

{ "mcpServers": { "sagefs": { "type": "sse", "url": "http://localhost:37749/sse" } } }

TUI / GUI / Web Dashboard / Jupyter

sagefs tui                # SageTUI Elm Architecture terminal UI
sagefs tui --legacy-tui   # Classic imperative CellGrid renderer (fallback)
sagefs gui                # GPU-rendered Raylib window
sagefs --jupyter conn.json  # Run as a Jupyter kernel
# Dashboard auto-starts at http://localhost:37750/dashboard

</details>

---

⌨️ Keybindings Across Editors

Action	VS Code	Visual Studio	Neovim
Evaluate selection/cell	Alt+Enter	Alt+Enter	<M-CR>
Evaluate entire file	Alt+Shift+Enter	Shift+Alt+Enter	<leader>rf
Clear inline results	Command Palette	—	<leader>rc
Run all tests	Command Palette	Command Palette	<leader>rT
Toggle test panel	Command Palette	View → SageFs Tests	:SageFsTestPanel
Jump to test source	Click test in explorer	—	<CR> in telescope
Show failure narrative	Hover on red marker	Hover on red marker	<C-d> in test panel
Mark all stale	Command Palette	Command Palette	<leader>rS
Session picker	Command Palette	Command Palette	<leader>rs

Full keybinding references: VS Code · Visual Studio · Neovim

---

🎨 Understanding the Gutter Icons

Icon	Meaning
✓ (green)	Test passing — this code is covered by at least one passing test
✗ (red)	Test failing — a test covering this code has failed
○ (gray)	No coverage — no test exercises this line
│ (green bar)	Coverage healthy — all tests covering this line pass
│ (red bar)	Coverage degraded — some tests covering this line are failing
│ (gray bar)	Not covered — no test reaches this line
⊘	Inline failure — shows the test name and Expected/Actual diff

💡 Hover over any gutter icon for details. In Neovim, press <C-d> on a failing test for the full failure narrative.

---

The $3,000/year Feature — Free

Visual Studio Enterprise charges ~$250/month per seat for Live Unit Testing. That's $3,000/year per developer. It only works in Visual Studio. It only supports 3 frameworks. It takes 5-30 seconds. It requires your code to compile.

SageFs does it better. In every editor. In under 500ms. On broken code. For free.

	VS Enterprise Live Testing	SageFs
Speed	5–30 sec (MSBuild rebuild)	200–500ms (FSI hot eval)
Broken code	✗ Must compile first	✓ Tree-sitter works on incomplete code
Editors	Visual Studio only	VS Code · Neovim · TUI · GUI · Visual Studio · Web
Frameworks	MSTest · xUnit · NUnit	+ Expecto · TUnit · xUnit v3 · extensible
Price	~$250/month	Free, MIT licensed

<details> <summary><strong>Three-speed feedback pipeline — how sub-500ms works</strong></summary>

<br />

1. ~50ms — Tree-sitter detects test attributes in broken/incomplete code → immediate gutter markers
2. ~350ms — F# Compiler Service type-checks → dependency graph, reachability annotations
3. ~500ms — Affected-test execution via hot-eval → ✓/✗ results inline

Tests are auto-categorized (Unit, Integration, Browser, Property, Benchmark, Architecture) with smart run policies — unit and property tests default to auto-run, integration/browser/architecture default to demand, and benchmarks stay disabled until explicitly enabled. All configurable.

</details>

---

Under the Hood

Hot Reload — File changes are detected, sent to FSI via #load, and Harmony patches method pointers at runtime. Connected browsers auto-refresh via SSE. Full details →

Multi-Session — Run multiple isolated F# sessions simultaneously, each in its own worker sub-process with independent FSI, project, and file watcher. Full details →

MCP Tools — 50 tools for code execution, testing, coverage analysis, and session management. Full reference →

SSE Events — All editors receive test_source_locations, file_annotations, and failure_narratives events tagged with SessionId. Full reference →

Architecture — Daemon-first design with isolated worker sub-processes and dual-renderer TUI/Raylib GUI. Full details →

<details> <summary><strong>🛡️ Supervised Mode — crash-proof development</strong></summary>

<br />

sagefs --supervised

Erlang-style supervisor with exponential backoff (1s → 2s → 4s → max 30s). After 5 consecutive crashes within 5 minutes, it reports the failure. Watchdog state exposed via /api/system/status and shown in the VS Code status bar. Use this when leaving SageFs running all day.

</details>

<details> <summary><strong>⚡ Standby Pool — instant hard resets</strong></summary>

<br />

SageFs maintains a pool of pre-warmed FSI sessions. Hard resets swap the active session for an already-warm one — near-instant recovery instead of a 30-60 second rebuild.

</details>

<details> <summary><strong>💾 Binary Session Persistence — instant resume</strong></summary>

<br />

SageFs persists session state and test caches to compact binary files (.sagefs v3, .sagetc v1) for near-instant cold starts. No JSON parsing, no database — raw binary with CRC-32C integrity checking.

• Session files (.sagefs): Full session state — interactions, diagnostics, outputs, eval timeline
• Test cache files (.sagetc): Test discovery results, outcomes, durations, bitmaps of affected tests
• Session isolation: Each session writes to its own file, verified by 176 property-based tests including concurrent write safety

Design: length-prefixed strings, section headers with byte-count envelopes, version negotiation, and field-level bounds checking prevent OOM from crafted inputs.

</details>

<details> <summary><strong>📋 CLI Reference</strong></summary>

<br />

Usage: sagefs [options]                Start daemon (bare by default)
       sagefs --supervised [options]   Start with watchdog auto-restart
       sagefs tui                      Terminal UI (starts daemon if needed)
       sagefs tui --legacy-tui         Terminal UI (imperative fallback)
       sagefs gui                      GPU GUI via Raylib (starts daemon if needed)
       sagefs --jupyter <conn.json>    Run as Jupyter kernel
       sagefs check                    Check environment before first run
       sagefs stop                     Stop running daemon
       sagefs status                   Show daemon info

Daemon options:
  --no-resume            Skip restoring previous sessions on startup
  --no-watch             Disable file watching for all sessions
  --prune                Mark all stale sessions as stopped, then exit
  --supervised           Auto-restart on crash (exponential backoff)
  --mcp-port PORT        Custom MCP port (default: 37749)

The daemon starts bare and waits for clients to create or connect to sessions.

Full options: sagefs --help

</details>

<details> <summary><strong>🔧 Configuration</strong></summary>

<br />

Per-directory config — .SageFs/config.fsx:

{ DirectoryConfig.empty with
    Load = Projects ["src/MyApp.fsproj"; "tests/MyApp.Tests.fsproj"]
    AutoOpenNamespaces = false
    InitScript = Some "setup.fsx" }

Set AutoOpenNamespaces = false to skip warmup auto-opening of namespaces and modules. Because sessions inherit .SageFs/config.fsx from the working directory, this opt-out applies across VS Code, Neovim, Visual Studio, the dashboard, TUI, and GUI session creation flows.

Built-in ways to create or edit that config:

• Dashboard — enter a working directory, then click Disable Warmup Auto-Open
• TUI / GUI — focus the sessions UI and press Ctrl+Alt+A
• VS Code — run SageFs: Configure Warmup Auto-Open
• Visual Studio — run SageFs: Configure Warmup Auto-Open
• Neovim — run :SageFsConfig

If .SageFs/config.fsx does not exist, these affordances create it with:

{ DirectoryConfig.empty with
  AutoOpenNamespaces = false
}

If the config already exists, SageFs opens or points you at the file instead of overwriting your existing settings.

Startup profile — ~/.SageFs/init.fsx auto-loads on every session start.

Precedence: Per-directory config > auto-discovery from working directory.

</details>

❓ Troubleshooting

Quick start: Run your editor's health check first (VS Code: Ctrl+Shift+P → "SageFs: Check Health" · Neovim: :checkhealth sagefs).

Problem	Quick Fix
"SageFs daemon not found"	dotnet tool install --global SageFs, then sagefs status
Port already in use	sagefs stop or --mcp-port 8080
Wrong project selected	"SageFs: Switch Project" in command palette
Stale REPL after code changes	Save the file first — source edits auto-reload. Use hard reset only for .fsproj / package changes.

📖 Full Troubleshooting Guide → — covers first-run issues, runtime problems, platform-specific fixes, and diagnostic tools.

📊 Feature Matrix → — compare features across VS Code, Neovim, Visual Studio, TUI, and Raylib GUI.

---

Welcome, Traveler 👋 — Pick Your Home Language

SageFs isn't just for F# veterans. Find your background below and get started with a guide that maps concepts you already know to F#, with runnable examples.

Quick orientation: Every sample in /samples is a runnable .fsx script. Open it in VS Code with the SageFs extension (or sagefs tui), hit Alt+Enter on any expression, and results appear inline. Instantly.

Background	One-liner	Guide
🐍 Python	Same REPL energy, plus a compiler that catches bugs before you run	Guide →
📓 Jupyter	Everything you love about notebooks, minus kernel crashes and JSON diffs	Guide →
🔷 C#	Same .NET, same NuGet — stop writing AbstractRepositoryFactoryImpl	Guide →
☕ Java	Expressive, type-safe, concise — what Java always wished it could be	Guide →
🟨 JS/TS	No undefined, no this bugs, no node_modules — just functions	Guide →
🦀 Rust	Option, Result, pattern matching — without the borrow checker	Guide →
🧘 F# Koans	You already know F# — now get instant feedback instead of dotnet run	Guide →

---

🎯 Visual Demos

See what SageFs makes possible beyond the REPL:

🌐 Reactive Web App — Falco + Datastar, zero JavaScript

A full CRUD todo app in ~100 lines of F#. Edit a handler, save — the browser updates before you look away. No webpack. No bundler. No framework ceremony.

→ samples/demos/webapp-datastar.fsx

🎨 GPU Window — Raylib Hello World with hot reload

A Raylib window that hot-patches on save. Change the color, the text, the animation — save — it's live in the running window. No restart, no flicker.

→ samples/demos/raylib-hello.fsx

🕹️ Interactive Game — live-tweakable physics

A playable star-catcher game. Edit starMaxSpeed, playerWidth, starColors in the source file, save, and the changes apply to the running game without interrupting play. This is what live development actually feels like.

→ samples/demos/raylib-game.fsx

---

Contributing

SageFs is open source and we welcome contributions! Whether it's a bug fix, documentation improvement, new test, or a whole feature — PRs are encouraged.

→ Read the Contributing Guide for setup instructions, debugging workflow, coding standards, and how to make your first PR.

New to the codebase? Check the Good First Contributions section in the contributing guide for places where help is especially welcome.

License

MIT

Acknowledgments

SageFs exists because of Jo Van Eyck's fsi-mcp-server — an elegant, minimal F# Interactive MCP server that proved the concept of connecting FSI to editors via MCP. That project was the catalyst that made everything here possible.

FsiX · sagefs.nvim · Falco & Falco.Datastar · Harmony · Ionide.ProjInfo · Raylib-cs · Fable · ModelContextProtocol