This is an experiment in testing the limits of agentic development, and so many of it's features are still in progress and not as well understood as I'd like. Feel free to submit issues, or pull requests, if you like. If you really need to get ahold of me, the most reliable way is on discord, so you can hit me up there, if you like, my name is the same on there, too.

What is SageFs?

SageFs is a live F# development engine. Start it once, then connect through VS Code, Neovim, Visual Studio, the web dashboard, or an MCP client to get sub-500ms feedback on every save: inline results, live test markers, hot reload, and agent access. It runs as a daemon with isolated session workers, so editors, dashboard tabs, and MCP clients can share 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
• 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.

Three Things That Change Everything

⚡ Hot Reload — Save and It's Live

🚧 Status: In progress — the reload pipeline (watch → eval → SSE refresh) is live, but propagating changes into a running app is still being completed for module-declared apps. See docs/hot-reload.md for the current status.

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

🖥️ One Daemon, Every Client — Simultaneously

Start SageFs once. Connect from VS Code, Neovim, Visual Studio, the web dashboard, or an MCP client. Open several at the same time: they can share a live session while retaining per-client session selection.

flowchart TB
    D[SageFs Daemon]

    D --- VS[VS Code]
    D --- NV[Neovim]
    D --- VI[Visual Studio]
    D --- WB[Web Dashboard]
    D --- AI[MCP Clients]
    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 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 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.

Web dashboard — Open http://localhost:37750/dashboard for session management, evaluation, output, test state, and diagnostics without an editor extension.

Deprecated frontends: The built-in SageTUI client, legacy TUI, and SageFs.Gui Raylib frontend are no longer current product interfaces. Their source remains in the repository for historical context. This does not affect Raylib application and game projects developed with SageFs; see the Raylib demos.

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.

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.

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.

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.

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.

🚧 Hot reload is in progress — the pipeline runs, but changes may not yet propagate into a running module-declared app. See docs/hot-reload.md.

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 your editor's command to switch workflows:

• Neovim: :SageFsWorkflow live or :SageFsWorkflow repl
• VS Code: Command Palette → SageFs: Switch Workflow
• MCP: use the session workflow tools exposed for the current state

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.

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 --- WB[Web Dashboard]
    D --- VI[Visual Studio]
    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 WB fill:#1a1b26,stroke:#bb9af7,color:#c0caf5
    style VI 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. Editor integrations, dashboard tabs, the Jupyter bridge, and MCP clients all connect to the same daemon. They create sessions, send code, and 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.

¹ 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 --jupyter conn.json  # Run as a Jupyter kernel
# Dashboard auto-starts at http://localhost:37750/dashboard

⌨️ Keybindings Across Editors

Full keybinding references: VS Code · Visual Studio · Neovim

🎨 Understanding the Gutter Icons

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

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. Status: in progress — see docs/hot-reload.md. 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, a web dashboard, editor integrations, and an affordance-driven MCP surface. Full details →

Repository Map — where things live

• 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, and worker HTTP transport; deprecated terminal client source is retained for historical context
• SageFs.Gui/ — deprecated Raylib product frontend retained as legacy source; it is separate from supported Raylib application and game projects
• 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, retained legacy projects, 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 --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
}

❓ Troubleshooting

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, the web dashboard, and MCP.

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 a supported editor with SageFs connected, hit Alt+Enter on any expression, and results appear inline. Instantly.

🎯 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