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.

• 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
• Repository Map
• 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.

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.

SageFs exposes a Model Context Protocol server with an affordance-driven state machine and a deliberately small tool surface — AI agents only see tools valid for the current session state, and the core MCP path stays focused on session trust, F# evaluation, exact test execution, and failure explanation. No wasted tokens guessing. Copilot, Claude, and any MCP client can execute F# code, type-check, verify a changed behavior, and run tests against your real project.

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.

flowchart 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

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

dotnet tool install --global SageFs

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.

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.

VS Code — Install the .vsix from Releases for now, 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.

⚠️ 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.

When live testing is enabled and a test session is loaded, save-triggered runs can update gutter state automatically. The core engine, SSE events, coverage data, and editor integrations are real today, but client polish and discovery/session behavior are still catching up. Expecto is the best-covered path right now.

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

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

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

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

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

Use your editor's command to switch workflows:

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

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.

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

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

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

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

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

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

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

{
  "mcp": {
    "sagefs": {
      "type": "remote",
      "url": "http://localhost:37749/sse",
      "enabled": true
    }
  }
}

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

Full keybinding references: VS Code · Visual Studio · Neovim

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

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 is building toward that same feedback loop with a REPL-centered architecture. The core live-testing engine is real, but the end-to-end experience is still being stabilized and is not equally polished in every client yet.

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 — 17 focused tools for session trust, code execution, exact test execution, failure explanation, and local friction reporting. 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 →

• SageFs.Core/ — shared engine and runtime logic: session management, MCP/session operations, live testing, persistence, and shared rendering primitives
• SageFs/ — CLI entrypoint, daemon host, MCP server, dashboard, worker HTTP transport, SageTUI client, and the legacy terminal renderer
• SageFs.Gui/ — Raylib GUI frontend
• SageFs.Tests/ — main Expecto test suite
• sagefs-vscode/ — VS Code extension (F# via Fable → JavaScript)
• sagefs-vs/ — Visual Studio extension workspace
• docs/ — user docs, architecture notes, troubleshooting, and feature references
• samples/ — runnable sample apps and language-onramp projects
• tests/ — Playwright/browser scenarios for dashboard and editor-facing UX flows
• scripts/ — repo helper scripts and smoke/integration utilities

SageFs.slnx covers the core tool, GUI, tests, and samples. The editor integrations live alongside it in sagefs-vscode/ and sagefs-vs/ because they use their own packaging toolchains and release flows.

The Neovim plugin is not in this repo — it lives in the separate sagefs.nvim repository.

If you're tracing the live testing / "test as you type" stack, start here:

• Engine, discovery, dependency graph, and coverage: SageFs.Core/Features/LiveTestingExecutors.fs, LiveTestingTypes.fs, CoverageInstrumenter.fs, TestDiscovery.fs, TestTreeSitter.fs
• Daemon routes, watchers, and SSE emission: SageFs/DaemonMode.fs, SageFs/McpServer.fs, SageFs/McpTools.fs
• VS Code client wiring: sagefs-vscode/src/Extension.fs, LiveTestingListener.fs, TestControllerAdapter.fs, FileAnnotationsListener.fs
• Visual Studio client wiring: sagefs-vs/SageFs.VisualStudio.Core/LiveTestingSubscriber.fs, SageFs.VisualStudio.Editor/TestStateTracker.cs, FileAnnotationTracker.cs, CoverageGlyphTagger.cs
• Neovim client wiring: the separate sagefs.nvim repo

sagefs --supervised

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)

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

{ DirectoryConfig.empty with
  AutoOpenNamespaces = false
}

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

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

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.

See what SageFs makes possible beyond the REPL:

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

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

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

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.

MIT

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