SageFS // Documentation
Write F# and watch your tests go green
Every line shows you whether it's covered by a test, whether that test passes, and what the last eval produced. Save the file and the affected tests re-run right away.
- Hot reload
- No restart for function-body changes and values bound to a lambda, even inside route tables built at startup
- MCP tools
- 72 gated by session state at call time
- Test framework coverage
- Expecto · xUnit (v2 and v3) · NUnit · MSTest · TUnit
- Editors
- VS Code · Neovim · Web Dashboard · MCP
Installation
dotnet tool install --global SageFsInstall the .NET 10 SDK or the .NET 11 SDK if you haven't already.
Install SageFS globally with the command above; no config files required.
Verify your environment: sagefs check validates your SDK, FSI, project files, port, and daemon state.
Start the daemon: sagefs. It starts the service and exposes the Web Dashboard while waiting for clients.
Connect an editor (see below) and press Alt+Enter on any expression.
Your first session
SageFS is a feedback loop. You write F#, send it, and the result shows up in your editor and your running app at the same time.
Open any .fs or .fsx file in a connected editor.
Send an expression to the engine: press Alt+Enter in Neovim or VS Code, or use the evaluator in the Web Dashboard.
Read the result inline. Each ;; is a transaction: a failure discards that one statement and keeps everything before it.
Save the file. In a Hot Reload session, SageFS patches an app running in the reload agent's process in place, including a route table built once at startup, and patches an app you started with run_app by metadata delta, restarting it with your change only when the delta can't take the save. In a Live Testing session, edits from the connected editor re-run the affected tests automatically. The gutter updates without you touching it.
Connect your editor
SageFS speaks Model Context Protocol. Prefer stdio: your client spawns sagefs mcp, which starts the daemon if it isn't running and bridges to it, so there's no ordering to get wrong. For Claude Code that's one command:
claude mcp add sagefs -- sagefs mcpA daemon that sagefs mcp starts lives as long as that agent session does. Start sagefs yourself first if you want it to stick around. A client that only speaks HTTP can use Streamable HTTP or SSE on port 37749, but the daemon has to be running before the client starts.
Works with GitHub Copilot (CLI & VS Code), Claude Code, Claude Desktop, OpenCode, Windsurf, Cursor, and any MCP-compatible tool. With the edit → auto-test → poll workflow, agents don't even need to call eval; they just edit files and check the live test status.
Editor extensions
VS Code: install SageFs from the Marketplace or Open VSX, or take the .vsix from GitHub Releases.
Neovim: install sagefs.nvim from its own repository; it follows each SageFs release.
Web Dashboard: http://localhost:37750/dashboard.
Per-client MCP config
Over stdio (preferred). GitHub Copilot (CLI), in ~/.copilot/github-copilot/mcp.json:
{ "servers": { "sagefs": { "type": "stdio", "command": "sagefs", "args": [ "mcp" ] } } }Claude Code: claude mcp add sagefs -- sagefs mcp. That lands in local scope, this project only; add -s user for every project, or -s project to write a .mcp.json you can commit:
{ "mcpServers": { "sagefs": { "command": "sagefs", "args": [ "mcp" ] } } }Cursor / Windsurf, in .cursor/mcp.json or the Windsurf MCP settings:
{ "mcpServers": { "sagefs": { "command": "sagefs", "args": [ "mcp" ] } } }OpenCode, in ~/.opencode.json:
{ "mcp": { "sagefs": { "type": "local", "command": [ "sagefs", "mcp" ], "enabled": true } } }Over HTTP, for a client that only takes a url (the daemon has to be running first). GitHub Copilot (CLI) uses Streamable HTTP at http://localhost:37749/:
{ "servers": { "sagefs": { "type": "http", "url": "http://localhost:37749/" } } }Claude Code, Claude Desktop, Cursor and Windsurf take the same url, with no transport field:
{ "mcpServers": { "sagefs": { "url": "http://localhost:37749/" } } }OpenCode uses SSE at http://localhost:37749/sse:
{ "mcp": { "sagefs": { "type": "remote", "url": "http://localhost:37749/sse", "enabled": true } } }The CLI
| Command | Description |
|---|---|
sagefs | Start the daemon and Web Dashboard; wait for editor, MCP, or browser clients. |
sagefs mcp | Speak MCP over stdio, starting the daemon first if it isn't running. The daemon it starts lives as long as the client does. |
sagefs check | Validate SDK, FSI, project files, port, and daemon state. |
sagefs status | Show daemon/port/session state. |
sagefs stop | Stop the running daemon. Exits 0 if a daemon was actually stopped, 1 if there was nothing to stop. |
sagefs sweep [--kill] | Report daemons whose owning process is gone; --kill also terminates them and removes the stale record. |
sagefs --mcp-port PORT | MCP port (default 37749, or SAGEFS_MCP_PORT). The dashboard runs on this port + 1 (default 37750). A port other than the default needs --owner-pid or --ttl. |
sagefs --owner-pid PID | Exit when the process at PID exits. For a daemon an agent, test or demo spawns. |
sagefs --ttl DURATION | Self-terminate after DURATION (30m, 1h, 90s) with no live sessions and no MCP or SSE clients. |
sagefs --supervised | Erlang-style watchdog with exponential backoff. |
sagefs --no-resume | Skip restoring previous sessions on startup. |
sagefs --prune | Mark all stale sessions stopped, then exit. |
Workflows
Every session picks one of three workflows when it's created. Switching workflow restarts the session, so REPL-defined bindings are lost, but your files on disk are untouched.
REPL (Interactive, the default): full type redefinition, tests run when you ask, manual browser refresh. Good for prototyping and domain modeling.
Live Testing: the same REPL, but affected tests re-run on every edit from a connected editor. Good for TDD.
Hot Reload: expression-level changes only (FS0037), so no type redefinition. Saving a change to a function body, or to a value bound straight to a lambda, updates the running app in place when it runs in the reload agent's process (started from FSI or an init script). An app you start with run_app runs in the worker, so a save there is patched in by a metadata delta, with its state, and restarts with your change only when the delta can't take it. In-place includes a route table captured by value at startup (the usual Falco/Giraffe/Saturn/Oxpecker setup). A value computed once at startup that something has already handed on, a mutable whose type changed, or a reshaped type restarts the app instead. Good for web apps.
Recently fixed: a save to an app started with run_app said Patched and changed nothing, because the reload agent lives in the FSI host and the app runs in the worker. It restarts the app with your change now, and since v0.6.882 a metadata delta keeps the app's state instead of restarting it when the delta can take the save. A test saves a file against a run_app app and checks what the running app prints. Before that: an app started by a .SageFs/init.fsx that #loads your sources used to restart on an edit (.NET 10) or get patched on the wrong copy while still saying Patched (.NET 11), and SageFS now tracks which copy of a function the app actually holds and patches that one, on both. Also shipped, each pinned by a real-app test on .NET 10 and .NET 11: untouched mutable state survives a reload, private state included; editing a live mutable's initializer keeps the live value, tells you, and gives you a reset; a redefined value gets its new value unless startup captured it. The hot-reload doc on GitHub tracks what's next.
A patch isn't reported as live just because the detour landed. A patched function stays PatchPending (the browser still refreshes) until its new body has been seen running, then it becomes Patched. If ten seconds pass and it never ran, it's NeverEntered and the message says to exercise it: an app nobody has used yet looks exactly like that. So does a function the JIT inlined into its caller, but only in a project built with optimizations. SageFS builds a session with -p:Optimize=false, where an F# inline call stays a call and the assembly is marked so the JIT does not inline either. If it finds an optimized build (a Release you built by hand), it marks the session Degraded and says so, because a patch can be bypassed there and nothing else would tell you. Nothing is claimed that wasn't observed.
Switch with the VS Code Command Palette or the workflow dropdown on the dashboard (both restart the same session in place), Neovim's :SageFsWorkflow (interactive, livetesting or hotreload; no name opens a picker; it restarts the same session in place too), or the switch_workflow MCP tool (accepts all three, but creates a new session and stops the old one).
Live testing
In a Live Testing session, edit code in a connected editor (VS Code or Neovim) and SageFS runs the affected tests automatically, then shows the result right in your gutter. You never have to leave the buffer to see whether your code passes. All five supported test frameworks discover, run, and report pass/fail correctly, and switching between sessions stays clean.
Test discovery runs on session start and after significant code changes; coverage is instrumented at the IL level.
The dependency graph finds affected tests from your unsaved edits; results stream back via SSE to editor gutters and panels. A plain save from any other tool is picked up by the daemon's file watcher and queued for live testing too.
Coverage bars, pass/fail glyphs, and failure narratives work. Source-mapped gutter markers and per-line coverage come through the editor's own integration, not the daemon directly.
Frameworks supported: Expecto, xUnit (v2 and v3), NUnit, MSTest, TUnit.
The gutter
The gutter is SageFS's signature feature. It shows, line by line, whether your code is tested and whether those tests pass, live as you type and save.
✓ Passing: the symbol is covered and its tests are green.
✗ Failing: the symbol is covered but at least one test is red.
○ No coverage: the symbol has no tests yet; write one and the marker turns green.
MCP server
SageFS runs a Model Context Protocol server with an affordance-driven state machine (source). tools/list always returns the full catalog, so a client sees every tool. The gate is on calling them: a tool that doesn't fit the session's current state gets refused up front with a structured error, so it doesn't fail halfway through. Call get_session_status to see which tools apply right now.
If you use an AI agent, install the SageFS skill first. Left alone, an agent does what agents do in every .NET repo: edit, dotnet build, wait, dotnet test, wait. The skill makes the REPL its inner loop instead, and it covers what to do when the agent drifts. There's a back_to_the_repl prompt, and a Claude Code hook that stops mid-task builds. Install it and read the rules in docs/agents.md.
Transport: stdio through sagefs mcp (recommended), or Streamable HTTP or SSE on port 37749 for a client that only speaks HTTP.
The edit → auto-test → poll loop: agents edit files, SageFS re-runs tests, and the agent reads live test status, with no eval round-trips.
72 tools are grouped by purpose (execution, sessions, testing, analysis, export, friction, leases, workspace hygiene, and multi-agent coordination) and gated by session state at call time, not list time.
The complete, current tool list lives in the engine's MCP tools doc.
MCP tool reference
The engine exposes 72 MCP tools grouped by purpose: execution, sessions, hot reload, testing/analysis, export, friction telemetry, leases for expensive work, workspace hygiene, and multi-agent coordination. The full catalog is always listed; calling a tool that doesn't fit the current session state gets rejected before it runs, not hidden from the list. The tables below are highlights; the engine's MCP tools doc is the complete, always-current list.
Code Execution & Status
| Tool | Description |
|---|---|
send_fsharp_code | Execute F# code. Each ;; is a transaction boundary. |
check_fsharp_code | Type-check a snippet without executing (current FSI context). |
cancel_eval | Cancel a running evaluation. |
get_session_status | Session health, loaded projects, and the tools available in the current state. |
get_recent_fsi_events | Recent evals, errors, and loads with timestamps. |
run_app | Run the session's executable project with hot reload (like dotnet run). |
stop_app | Stop the app started by run_app; the session keeps running. |
list_runnable_projects | List the session's projects and which ones run_app can run. |
Sessions & Status
| Tool | Description |
|---|---|
get_available_projects | Discover .fsproj/.sln/.slnx files. |
create_project_session | Create an isolated FSI session for one explicit .fsproj. |
list_sessions | List all active sessions. |
switch_session | Switch active session. |
switch_workflow | Switch between REPL, Live Testing, and Hot Reload workflows. |
stop_session | Stop a session by ID. |
reset_fsi_session | Soft reset: clear definitions, keep DLLs. |
hard_reset_fsi_session | Full reset: rebuild, reload, fresh session. |
enable_hot_reload | Enable file watching / hot reload for the session. |
disable_hot_reload | Disable file watching / hot reload for the session. |
Testing, Verification & Coverage
| Tool | Description |
|---|---|
list_tests | List discovered tests, grouped by file with source locations. |
run_tests | Run the session's tests through the live-testing engine and get a receipt. A pass from an earlier run never counts, and Incomplete is not green. |
targeted_verify | Plan a trustworthy verification pass for one changed behavior; refuses to claim green on stale code. |
explain_test_failure | Enriched failure context for a test that recently went Passed→Failed. |
diagnose | Full diagnostic report: test failures, cell staleness, ripple plan, suggestions. |
coverage_intel | Analyze test coverage quality: blind spots, correlated failures. |
impact_forecast | Forecast performance impact and downstream blast radius for cells. |
suggest_next_action | Prioritized next-action queue combining coverage, impact, staleness. |
suggest_next_cell | Type-directed suggestions for what to evaluate next, from bindings in scope. |
suggest_repair | Given a failing test, trace causal changes and suggest the symbol to fix. |
plan_ripple | Plan cascade re-evaluation for changed cells using the dependency graph. |
preview_what_if | Preview what would change if a binding had a different value, without executing. |
decompose_pipeline | Decompose an F# pipeline into stages with purity classification. |
get_cell_dependencies | Expose the cell dependency graph with staleness annotations. |
discover_features | Context-aware feature discovery ranked by relevance. |
Friction Telemetry (local)
| Tool | Description |
|---|---|
get_friction_summary | Compact summary of MCP friction (local). |
get_friction_report | Structured JSON report of MCP pain points (local). |
report_friction | Record structured feedback about a confusing tool call (local). |
Multi-Agent Coordination (Cohort)
For running several agents against one repo at once. The first agent to join a daemon's cohort becomes its conductor; identity is resolved from the MCP connection itself, not from a name argument.
| Tool | Description |
|---|---|
join_cohort | Join the daemon's shared coordination session. |
leave_cohort | Leave; any claims you hold are orphaned for the conductor to reassign. |
get_cohort_status | Members, claims, the test matrix, and the landing queue. |
acquire_claim | Take an exclusive claim on a file or project so other agents know it's yours to edit. |
release_claim | Release a claim you hold. |
reassign_claim | Conductor-only: reassign an orphaned claim. |
request_landing | Queue a landing: your commits are rebased onto the integration head, verified, and fast-forwarded in, one at a time. |
set_integration_ref | Conductor-only: set the git ref landings rebase onto. |
A broader HTTP API (under /api/...) covers live testing, completions, exploration, session control, and event history for the Web Dashboard and editor plugins. The MCP tools above are the smaller, deliberate set exposed to AI agents.
Troubleshooting
Port 37749 in use: stop the other daemon (sagefs stop), or start yours on another port with SAGEFS_MCP_PORT and point your clients at it. A port other than the default needs --owner-pid or --ttl as well, so a daemon that is somebody's temporary one says who owns it or when to give up.
Daemon won't start: run sagefs check; it reports SDK, FSI, project, port, and state problems.
Stale daemon serving old code: results that don't match what you just wrote, a session faulting on a project that builds fine, or an error naming Could not load file or assembly 'System.Runtime, Version=N.0.0.0' (or a type not found, Version=... mismatch) all mean the same thing: the daemon is older than your code and keeps serving the assemblies it started with. Nothing warns you. Check sagefs status, and if it's behind, restart on a current build: dotnet tool update -g sagefs for the global tool. That command can report you're already up to date even when a newer version is on NuGet, because tool update resolves through NuGet's search index, and that index lags the package store by a few minutes. Pass --version X.Y.Z to get past it. Hit this myself on 0.6.822.
FSI errors on eval: a failed ;; discards only that statement; fix it and resend. Use reset_fsi_session for a clean slate.
Project not loading: confirm the .fsproj/.slnx is discoverable via get_available_projects and that it builds standalone.
Hot reload not showing your change? Look at what you edited. A function body or a value bound straight to a lambda reloads in place, even inside a route table built at startup (the usual Falco/Giraffe/Saturn/Oxpecker setup). A value computed once at startup that something has already handed on, a mutable whose type changed, or a reshaped type restarts the app instead, and SageFS logs why. If you started the app with run_app, a save is patched in place by a metadata delta and your state stays. When the delta can't take it (a field added, a signature changed) the app restarts with your change, and SageFS names the declaration. SAGEFS_METADATA_DELTA=off in the daemon's environment turns the delta route off, and then every run_app save restarts the app (about six seconds on the ticker demo).
Where the logs are: the daemon writes mcp-server<yyyyMMdd>.log in its log directory (the SageFs folder under your local application data directory, or SAGEFS_DATA_DIR if that is set), rolls a file at 50 MB and keeps 7. GET http://localhost:37750/api/daemon-info returns the current path as logPath. Each session's worker writes <data dir>/workers/<sessionId>.log (the data dir is ~/.SageFs unless SAGEFS_DATA_DIR says otherwise), capped at 4 MiB with one .log.1 generation behind it. While a worker starts, the daemon keeps the last 200 lines of its stderr and attaches the last 20 to the failure reason if the worker dies or goes quiet. See Where the logs are.
Health says Degraded: it means three different things. A session is Degraded when it works but something you'd expect won't: a project was loaded by hand-parsing the .fsproj because MSBuild evaluation failed (no run_app, no hot reload; run dotnet build and read the first MSBuild error), a project was built with optimizations (a hot-reload patch can be bypassed by inlining; run hard_reset_fsi_session with rebuild=true), or warmup loaded nothing (usually the project was never built). The daemon's overall reading in /health is Degraded when a session is Faulted, when the machine's memory is tight, or when the session manager's supervisor reports trouble: its loop restarted, a command failed, or one command has held it longer than SAGEFS_SUPERVISOR_WEDGE_SECONDS (30 by default; restart the daemon if a wedge doesn't clear). It is Unhealthy at critical memory, or when one of the daemon's own telemetry signals has broken from its normal. See When health says Degraded.
No file events for a session: a session whose working directory is your home directory, a directory that holds it, or a filesystem root is refused a file watcher, because one recursive watch there would cost an inotify watch per directory. /health lists it under componentFailures as file-watcher:<directory> with a hint to open the session in a project directory, not the home directory or a filesystem root, and restart it. Until then, hot reload and live testing get no file events for that session. See file watching.
A live binding shows as unreadable: the live bindings view runs your property getters to walk a value. A Task is shown by its status and never waited on, a Lazy as created or not and never forced, and a getter that doesn't return within one second shows as unreadable and isn't walked again. Not covered yet: a getter in an infinite loop leaves a thread spinning a core for the life of the host, and a stack overflow inside a getter kills the host and the session. See the live_bindings notes.
Changing a timeout or interval: every SAGEFS_* environment variable, with its default, its unit and what it is for, is listed on the configuration page. Set them in the environment that starts the daemon and restart it.
FAQ
Is SageFS free?
Yes. SageFS is open source under the MIT License and free for everyone, including commercial use.
Which editors are supported?
VS Code, Neovim, the Web Dashboard, and any MCP client.
Does it work with my existing project?
Yes, for modern .NET (Core) projects. Point it at any .fsproj/.sln/.slnx, no config files required. .NET Framework projects aren't supported yet: SageFS's FSI host runs on modern .NET and can't load Framework assemblies, so it refuses those projects with a clear reason instead of failing halfway through. Tracked at issue #135.
What about AI agents?
Any MCP client can drive SageFS: execute F#, type-check, run tests, and read live status through a set of tools gated by session state (see the full MCP tool list).
Repository map
SageFS is one repository with a handful of parts (mirroring the engine README's repository map): the engine is one daemon, and everything else plugs into it. The Neovim plugin is a separate repo.
SageFs.Core/: the shared engine and runtime logic (session management, MCP/session operations, live testing, persistence, shared rendering primitives).
SageFs/: CLI entrypoint, daemon host, MCP server, Web Dashboard, and worker HTTP transport (ports 37749 / 37750).
SageFs.Host/: the worker sub-process every session spawns. SageFs.FsiHost/: source for the isolated FSI host, built fresh with each project's own .NET SDK. SageFs.Simulation/: deterministic simulation models that fold the real cores (file-reload routing, worker lifecycle, supervision, the manifest).
SageFs.Tests/: main Expecto test suite, including its own browser scenarios written in F# with Playwright.NET (the repo's test-count badge is auto-derived from the live suite, 13,000+ cases).
sagefs-vscode/: VS Code extension (F# via Fable → JavaScript).
docs/: user docs, architecture notes, troubleshooting. samples/: runnable demos, including Raylib app and game projects whose hot reload is not covered by an automated test. scripts/: helper utilities.
sagefs.nvim: the Neovim plugin, a separate repository.