SageFs
Sage Mode for F# development — REPL with solution or project loading, Live Testing for FREE, Hot Reload, and session management.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/WillEhrendreich/SageFs with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/WillEhrendreich/SageFs'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/willehrendreich--sagefs)HTML
<a href="/listings/willehrendreich--sagefs"><img src="/api/listings/willehrendreich--sagefs/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
You need the [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or the .NET 11 SDK. The tool ships a build for each and `dotnet` picks the one that matches yours. Nothing else.
dotnet tool install --global SageFs
To update later: `dotnet tool update --global SageFs`. If that says "already installed" when you know a newer version is out, add `--version X.Y.Z` because `dotnet tool update` resolves through NuGet's search index, which lags the package store by a few minutes.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
Readme.md · README · 800 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <div align="center">
- # SageFs
- ### You save. The affected tests re-run. The running app serves the new code.
- Your F# project, loaded once and kept running. Ask it whether a snippet type-checks against your loaded project and it answers in about 20 milliseconds, on a 300-line sample or an 86,000-line engine. (Checking the whole project without a build is not a tool yet.) Tests re-run on edits you haven't saved. A save reaches the app that's already running, with its state. VS Code, Neovim, a browser dashboard and your AI agent all work in that one live session. Free, MIT.
- [](https://www.nuget.org/packages/SageFs/)
- [](https://dotnet.microsoft.com)
- [](LICENSE)
- []()
- []()
- </div>
- ## What is SageFs?
- Hey, I'm Will. Every .NET workflow I've used has the same shape. You change a file, something rebuilds, something restarts, and then you find out whether you were right. On this repo's engine that is about fifty seconds of build before a single test starts. SageFs is what I built so I'd stop waiting to find out.
- The idea is small. Your project is loaded into one live F# session and stays there, warm and running. Anything that wants to know something about your code asks that session, instead of rebuilding the code to find out.
- | You want to know | Rebuilding | Asking the live session |
- |:---|:---|:---|
- | Does this snippet type-check against my project? | `dotnet build` of the whole project: 2 s on a 300-line sample, 49 to 52 s on projects of 22,000 and 86,000 lines | `check_fsharp_code` on one snippet in a warm session: 21 to 25 ms on all three, because the work is the snippet and not the project. It is a smaller question than a build answers, and a snippet that passes here can still fail `dotnet build`. A whole-project check without a build is not a tool yet ([the numbers](docs/repl-loop-benchmarks.md), [what is missing](docs/roadmap.md)) |
- | Did I break a test? | Build, then run the tests | The tests the edit can reach re-run on the edit, saved or not: 0.7 s from keystroke to verdict on the 11-test sample I measured ([how live testing works](docs/how-live-testing-works.md)) |
- | Does my running app do the new thing? | Stop, build, start, click back to where you were | Save. The changed methods are re-pointed in the process that's already running and its state stays. A save was served in 1.8 to 2.6 s on the test fixture, against 6 to 8.5 s for the restart it replaced ([how hot reload works](docs/how-hot-reload-works.md)) |
- Those were measured on one machine with other work running, and each page says where its number stops being true.
- Because it is one session, the rest follows. VS Code, Neovim and the browser dashboard all look at the same live program at once, each with its own view. An AI agent stops shelling out to `dotnet build` and guessing: it type-checks, evals and runs your tests in the session you are looking at, and every test run comes back with a receipt that says what source it ran on, so a pass on stale code never counts as green. When several agents work in one repo they join a cohort, with claims on files and landings that are verified before they reach the trunk, and the rules of that coordination are checked by deterministic simulation.
- None of the pieces is new on its own. Visual Studio has Live Unit Testing, C# has hot reload, and Smalltalk and Clojure people have lived inside running programs for decades. What I couldn't find was F# getting any of it, or all of it hanging off one session that you and your agents share. Where Microsoft's version is ahead I say so on the pages that compare them.
- The pages keep themselves honest. Nothing on [the roadmap](docs/roadmap.md) is marked done by hand: an item moves to Built when its code shows up in the tree, and a test fails if the page and the code disagree. The tool counts you read here are held to the same rule.
- ### F# Interactive is amazing. Here's what I wanted on top of it.
- Type an expression, get the answer, no build step. FSI is one of the best things about F# and I use it all day. I'm not trying to replace it, SageFs *is* FSI underneath. But everybody who's used `dotnet fsi` on a real project has run into the same things:
- - **It starts empty.** Your project, your packages and your `open`s are all on you, through `#r` and `#load`, every time.
- - **It's one process in one terminal.** A bad eval or a hang takes the session with it, and nothing else can use it while you do.
- - **It knows nothing about your tests.** Change a function, run `dotnet test`, wait.
- - **It can't touch a running app.** Edit a handler in a web app and it's stop, build, start, click back to where you were.
- - **Values scroll away.** You see `val x : int = 3` once, then it's gone off the top of the terminal.
- - **Only you can drive it.** An AI agent can't sit in your REPL, so it shells out to `dotnet build` like it's 2015.
- ### What SageFs does about it
- Start `sagefs` once. Then:
- | On a real project, FSI | With SageFs |
- |:---|:---|
- | It starts empty | A session loads your real project, built by the SDK `dotnet` picks in that folder, in its own host process. Your package versions never fight mine. No config files, and it works on half-written code. |
- | One process, one terminal | One daemon, any number of isolated session workers. VS Code, Neovim, the dashboard and agents all talk to the same live session at the same time, and each keeps its own view. |
- | It knows nothing about your tests | Edit a function, saved or not, and the *affected* tests re-run against it. The failing one goes red in your editor and green again when you fix it, without touching the file on disk. Each line lists the tests that run it, each result says whether it ran against evaluated code or a real build, you can pause it or scope it to some tests, and in VS Code you can debug the failing test. When it can't tell what an edit affects it runs everything, it never reads an empty selection as green. See [live testing](docs/live-testing-as-you-type.md). |
- | It can't touch a running app | Save a `.fs` file and SageFs re-points the changed methods in the process that's already running, including inline lambdas in a route list, instance members, and code you added, removed or gave a new signature. Your state stays where it was. A new member on an existing type restarts the app, and so does anything else it can't patch, and it says why. See [hot reload](docs/hot-reload.md). |
- | Values scroll away | Every binding in your session is shown live in the dashboard, top-down, and updates after each eval. |
- | Only you can drive it | An MCP server with [74 tools](docs/mcp-tools.md). An agent evals, type-checks and runs your tests in the same session you're looking at, and `run_tests` hands back a receipt so a stale pass never counts as green. |
- Those rows are what the code does today. Which release each piece first shipped in is the progress page's job, not this one's: [what SageFs has become, stretch by stretch](docs/progress.md).
- For the curious, there are three short write-ups on how it's done, each with the tools I learned from, what F# and .NET don't hand you, how SageFs gets it done, and where Microsoft's version is ahead: [how hot reload works](docs/how-hot-reload-works.md), [how live testing works](docs/how-live-testing-works.md), and [how SageFs opens projects plain FSI can't](docs/how-isolation-works.md).
- If you want to see where it's going, [the roadmap](docs/roadmap.md) lists what I'm building now, what's next, and the ideas further out. It updates itself: an item moves to Built when its code lands.
- I'm not going to pretend all of that is finished. [Live testing](docs/live-testing-as-you-type.md) and hot reload each have documented limits, written down next to the tests that pin them. But all of it runs today, and none of it is a mockup.
- **How's it different from Ionide?** Ionide gives you the editor smarts (IntelliSense, diagnostics, project support) through the F# Compiler Service, and it's great. SageFs adds live *execution*: eval any expression and see the result inline, continuous test feedback on every save (or keystroke, if you want it), and hot reload that patches your running app. Use both together: Ionide for editing, SageFs for running. They get along fine.
- **How's it different from `dotnet watch`?** `dotnet watch` rebuilds when you save. SageFs keeps your project loaded, so it re-runs only the tests an edit can reach, before you save if you like, and it patches a running F# app where `dotnet watch` restarts it. `dotnet watch` is the better pick for a small app or a C# project, and it needs nothing installed. [The comparison, row by row](docs/vs-dotnet-watch.md).
- My CI runs on Linux only, so nothing automated covers Windows or macOS. The tool is a .NET global tool and the package is built to install on both. Windows is untested here, so tell me what breaks. On macOS, one contributor has run SageFs on an Apple Silicon Mac, and four issues from that work are open. Five hot reload detour tests fail there (`GenericReloadTests`, "the real detours") and nobody knows why yet ([#149](https://github.com/WillEhrendreich/SageFs/issues/149)); nobody has tried an Intel Mac. Live testing did not react to a saved file in 9 of 9 saves in the reporter's repro, which passes on Linux ([#174](https://github.com/WillEhrendreich/SageFs/issues/174)). A `net10.0` project with no `global.json` faulted in warmup on a Mac with SDK 11 installed, and the error named no cause ([#183](https://github.com/WillEhrendreich/SageFs/issues/183)). Twelve hygiene tests threw `KeyNotFoundException`; the fix shipped in 0.6.914 and the issue stays open until that Mac user confirms it ([#148](https://github.com/WillEhrendreich/SageFs/issues/148)). So treat live testing and hot reload on macOS as unproven, and expect the same of everything else there, because nothing automated runs on a Mac. Pin the SDK with a `global.json` to avoid #183. SageFs itself installs with the .NET 10 SDK or the .NET 11 SDK. Your *projects* aren't stuck on that version though. Each session's host gets built with whichever SDK `dotnet` picks in your project's folder, and runs on that SDK's runtime. So a `global.json` pin is honored, and without one you get the newest SDK you have installed. If you want a project on .NET 10 while an 11 preview is also installed, pin it with `global.json`.
- This started as an experiment in how far agentic development could go, and it's grown into the tool I use every day. It's moving fast, it's got rough edges, and you WILL find things you wish worked differently. That's exactly the feedback I want. Feel free to submit issues or PRs, and if you really need to get ahold of me, Discord is the most reliable way, same name there too.
- ## Table of Contents
- - [Key Features](#key-features)
- - [Get Started](#get-started)
- - [Three Workflows: REPL, Live Testing, and Hot Reload](#three-workflows-repl-live-testing-and-hot-reload)
- - [How SageFs Works](#how-sagefs-works)
- - [What You Get in Each Editor](#what-you-get-in-each-editor)
- - [Keybindings](#%EF%B8%8F-keybindings-across-editors)
- - [Test and coverage marks](#-test-and-coverage-marks)
- - [Live Testing Cost Comparison](#live-testing-cost-comparison)
- - [Under the Hood](#under-the-hood)
- - [Repository Map](#repository-map-where-things-live)
- - [Coming from Another Language?](#coming-from-another-language)
- - [Visual Demos](#-visual-demos)
- - [Contributing](#contributing)
- - [License](#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 as soon as you press Alt+Enter.
- >
- > 🐍 [Python](docs/coming-from-python.md) · 📓 [Jupyter](docs/coming-from-jupyter.md) · 🔷 [C#](docs/coming-from-csharp.md) · ☕ [Java](docs/coming-from-java.md) · 🟨 [JS/TS](docs/coming-from-javascript.md) · 🦀 [Rust](docs/coming-from-rust.md) · 🧘 [F# Koans](docs/coming-from-koans.md)
- >
- > Or just dive in: `dotnet tool install --global SageFs && sagefs`, then open any `.fsx` file and hit Alt+Enter.
- ---
- ## Key Features
- ### ⚡ Hot Reload
- Save a `.fs` file and SageFs figures out which functions changed and uses [Harmony](https://github.com/pardeike/Harmony) to re-point those methods in the process that's already running. No rebuild, no restart, and yes, that includes apps whose route table was only ever built once at startup. Connected browsers refresh automatically over SSE.
- Because it re-points **methods**, not everything is patchable: a handler that's *called* per request reloads, a handler whose output was *computed once* at startup can't. Prefer `let getHome (ctx: HttpContext) = ...` over `let getHome : HttpHandler = Response.ofHtml (pageLayout [])`. Lambdas in your route list, instance members, added or removed functions, a changed signature, and generic functions in every instantiation all patch in place. Reshaping a type, adding a member to an existing type, and a `let mutable` whose type changed restart the app and say why instead of pretending to reload.
- Apps started by a `.SageFs/init.fsx` that `#load`s your sources patch in place too, on .NET 10 and .NET 11. SageFs tracks which copy of a function the app is actually holding and patches that one.
- How you start the app matters, and I'd rather tell you than have you find out. An app started from FSI or an `init.fsx` lives in the same process as the reload agent, so a save patches it in place and its state stays put. An app started with `run_app` runs in the worker, out of the agent's reach. SageFs patches it in place with a metadata delta, so the app keeps its state and a save comes back in a couple of seconds instead of a full restart. A save the delta can't take (a field added, a new lambda that adds a closure class, a signature change) still restarts and names the declaration, and `SAGEFS_METADATA_DELTA=off` turns the route off. The table and the source links are in [docs/hot-reload.md](docs/hot-reload.md#how-you-start-the-app-decides-which-of-two-things-happens).
- A detour landing isn't reported as live. A patched function stays `PatchPending` (the browser still refreshes, because the change may well be live) until its new body has been seen running, and then it becomes `Patched`. If ten seconds go by and it never ran, it's `NeverEntered`, and the message says to exercise it. An app nobody has clicked on yet looks exactly like that, so the wording stays at "unconfirmed". 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.
- Your app's live state survives a save. A `let mutable` you didn't touch keeps its value, private ones included. Edit a mutable's initializer and the app keeps its live value, SageFs tells you what it kept, and the dashboard's Hot Reload panel (or the `reset_hot_reload_state` MCP tool) has a Reset for when you want the new initializer to run. Redefine a plain `let` value and it gets its new value, as long as nothing in the running app kept a copy of the old one. The app tells SageFs where every read of it went, so if startup put it in a closure, or a `lazy` cached it, or a handler that hands it on already ran, it's a restart that names who kept it, never a fake Patched. The details, and where that falls short, are in [docs/hot-reload.md](docs/hot-reload.md#values).
- > **Curious how this is possible on F#?** [How hot reload works](docs/how-hot-reload-works.md) covers the Erlang, Clojure and Smalltalk ideas it borrows, what .NET doesn't give F# by default, and how it compares with .NET's own hot reload.
- > **[docs/hot-reload.md](docs/hot-reload.md) is the authority.** It carries the full what-reloads / what-restarts table, each row pinned by an executable test, plus [the measured timings](docs/how-hot-reload-works.md#how-long-a-save-takes) with the machine and run count stated on the page. This README deliberately doesn't duplicate it, so the two can't drift apart.
- ### 🤖 AI Agent Support
- SageFs exposes a [Model Context Protocol](https://modelcontextprotocol.io/) server with an affordance-driven state machine: the full tool catalog is always listed, but calling a tool that doesn't apply to the current session state gets rejected with a structured error instead of a raw failure. `get_daemon_status` reports daemon health, and `get_session_status` reports the selected session and its available tools. The core MCP path is session trust, F# evaluation, running tests, and failure explanation. `run_tests` asks the same live-testing engine the dashboard and the editors use and hands back a receipt: a pass left over from an earlier run never counts, and `Incomplete` is not green. Copilot, Claude, and any MCP client can execute F# code, type-check it, verify a changed behavior, and run tests against your real project.
- Agents left alone will happily pile on complexity. Give one a fast, type-checked REPL with tests re-running on every change and it gets caught the same way I do, right away.
- > **If you're using an agent, read [docs/agents.md](docs/agents.md) first and install the [SageFs skill](skills/sagefs/SKILL.md).** An agent that doesn't know the rules goes straight back to `dotnet build`, wait, `dotnet test`, wait, and you lose the whole point. The skill makes the REPL its inner loop. The page also shows how to pull an agent back when it drifts: a `back_to_the_repl` prompt, and a Claude Code hook that stops mid-task builds.
- ### 🖥️ One Daemon, Every Client
- Start SageFs once, then connect from VS Code, Neovim, the web dashboard, or an MCP client. Open several at once and they share a live session, with each client keeping its own selection. Pair with your agent, watch it work in the dashboard, keep typing in Neovim, all at the same time.
- ```mermaid
- flowchart TB
- D[SageFs Daemon]
- D --- VS[VS Code]
- D --- NV[Neovim]
- 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 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
- The short version, for people who read the last page of the book first:
- 1. `dotnet tool install --global SageFs`, then make sure `~/.dotnet/tools` is on your `PATH`.
- 2. `sagefs check` tells you what's missing, with a fix next to each failure.
- 3. Run `sagefs` in a terminal and leave it there, or run it as a [service](#run-it-as-a-service-linux).
- 4. Open `http://localhost:37750/dashboard`, or point your editor or agent at it (step 4 below).
- 5. `sagefs status` says whether the daemon is up. Exit code 0 means up and healthy, 1 not running, 3 up with a failed component (it names which), 4 wedged (a process holds the port and never answers).
- ### 1. Install SageFs (30 seconds)
- You need the [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or the .NET 11 SDK. The tool ships a build for each and `dotnet` picks the one that matches yours. Nothing else.
- ```bash
- dotnet tool install --global SageFs
- ```
- Run the install from a folder whose `dotnet --version` is the SDK you want SageFs on, such as your home directory. Inside a project whose `global.json` pins an older SDK (8 or 9), the install runs under that SDK and NuGet refuses the package. The build you get is fixed at install time: with only SDK 10 installed you get the net10.0 build, which cannot load a net11.0 project, and `dotnet tool update` keeps that build. `sagefs --version` says which one you have (`SageFs version 0.6.945.0 (net10.0, .NET 11.0.0)`). To move to the net11.0 build after installing SDK 11: `sagefs stop`, `dotnet tool uninstall --global SageFs`, then `dotnet tool install --global SageFs` from a folder where `dotnet --version` prints 11.x.
- To update later: run `sagefs stop` first (with the [service](#run-it-as-a-service-linux), `systemctl --user stop sagefs`), then `dotnet tool update --global SageFs`. A running daemon holds the installed executable, and on Windows the update then fails with "The file exists" (see [Troubleshooting](docs/TROUBLESHOOTING.md)). If the update says "already installed" when you know a newer version is out, add `--version X.Y.Z` because `dotnet tool update` resolves through NuGet's search index, which lags the package store by a few minutes.
- ### 2. Check your environment (optional)
- ```bash
- 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
- ```bash
- sagefs
- ```
- SageFs runs in the foreground, streaming daemon logs to that terminal. It's not an F# REPL by itself. Leave it running, 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.
- SageFs writes `<project>/.SageFs/warmup-replay-cache.json` the first time it warms a project up, and a `.gitignore` right beside it. That cache is machine-generated, and the `.gitignore` ignores the cache, its temp file and itself, so your `git status` stays clean. If that folder already has a `.gitignore`, SageFs adds the cache to it and leaves the rest of the file alone. The exception is one that holds exactly what earlier versions of SageFs wrote (the cache entry alone): SageFs rewrites that file so it ignores itself too. `config.fsx` and `init.fsx` are yours. Those two you commit.
- ### Run it as a service (Linux)
- The daemon that `sagefs mcp` starts for an agent is owned by that agent (see [how long the daemon lives](docs/mcp-tools.md#how-long-the-daemon-lives)). When the agent exits, the daemon, its sessions and the dashboard go with it. If you'd rather have one that's just there, let systemd babysit it:
- ```bash
- if [ "$(printf '%s' "$PATH" | tr -d '"%\\\n')" != "$PATH" ]; then
- echo "Your PATH holds a \", %, \\ or line break, which the install cannot copy into the unit, so nothing was installed." >&2
- else
- mkdir -p ~/.config/systemd/user/sagefs.service.d
- cp contrib/systemd/sagefs.service ~/.config/systemd/user/
- printf '[Service]\nEnvironment="PATH=%s"\n' "$PATH" > ~/.config/systemd/user/sagefs.service.d/path.conf
- systemctl --user daemon-reload
- systemctl --user enable sagefs
- systemctl --user restart sagefs
- fi
- ```
- [`contrib/systemd/sagefs.service`](contrib/systemd/sagefs.service) is a user unit. It runs `~/.dotnet/tools/sagefs --supervised`, restarts it on failure, and starts it at login (`loginctl enable-linger $USER` if you want it at boot). `systemctl --user status sagefs` shows it, `journalctl --user -u sagefs` has its logs. A user unit doesn't read your shell profile, so without help the daemon and everything it starts get systemd's default `PATH`, and an `init.fsx` that runs `npm` (or a script that calls `dotnet`) can't find it. So the install writes the `PATH` of the shell you run it in to a drop-in, `~/.config/systemd/user/sagefs.service.d/path.conf`, beside the unit. The unit itself stays the same for everyone, so it holds no `PATH` of its own. A `PATH` with a `"`, `%`, `\` or line break in it would come out of the drop-in changed, so the install stops instead. To make the daemon see a `PATH` change, such as a new tool or another node version from nvm, run the install again: it rewrites the drop-in and restarts the service. The unit runs the daemon from `~/.local/state/sagefs`, which systemd creates (`StateDirectory=`), and not from your home directory: a request that names no directory falls back to the daemon's cwd, and SageFs refuses to watch a home directory, so a daemon started in `$HOME` would give you sessions with no hot reload and no live testing ([`FileWatcher.fs`](SageFs.Core/FileWatcher.fs), `classifyWatchRoot`). When an agent then runs `sagefs mcp`, it finds your daemon already up and just bridges to it, so nothing it does can take the daemon down.
- The supervisor starts a new daemon whenever the old one is gone, so `sagefs stop` gets you a fresh one, and it says so (exit code 3). To stop the service, run `systemctl --user stop sagefs`; `systemctl --user disable sagefs` keeps it from starting at login. To restart it, say after `dotnet tool update --global SageFs`, run `systemctl --user restart sagefs`. If the daemon crashes over and over, the watchdog gives up and exits 1, and after three give-ups in ten minutes systemd marks the unit failed; fix the cause (`journalctl --user -u sagefs`), then `systemctl --user reset-failed sagefs` and `systemctl --user restart sagefs`.
- ### Run it as a service (macOS)
- On a Mac, launchd does the babysitting. launchd expands no variables in a plist, `~` included, so the install fills in your home directory, your .NET folder and your `PATH` as it copies the file. Run it from the repo root:
- ```bash
- dotnet_root="$(dirname "$(realpath "$(command -v dotnet)")")"
- if [ ! -x "$dotnet_root/dotnet" ]; then
- echo "No dotnet found through PATH, so nothing was installed. realpath needs macOS 12.3 or later." >&2
- elif [ "$(printf '%s' "$PATH" | tr -d '|&<\\\n')" != "$PATH" ]; then
- echo "Your PATH holds a |, &, <, \\ or line break, which the install cannot copy into the plist, so nothing was installed." >&2
- else
- launchctl bootout gui/$(id -u)/io.github.willehrendreich.sagefs 2>/dev/null
- mkdir -p ~/Library/LaunchAgents ~/Library/Logs/sagefs "$HOME/Library/Application Support/sagefs-daemon"
- sed -e "s|@HOME@|$HOME|g" -e "s|@DOTNET_ROOT@|$dotnet_root|g" -e "s|@PATH@|$PATH|g" \
- contrib/launchd/io.github.willehrendreich.sagefs.plist \
- > ~/Library/LaunchAgents/io.github.willehrendreich.sagefs.plist
- launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.github.willehrendreich.sagefs.plist
- fi
- ```
- [`contrib/launchd/io.github.willehrendreich.sagefs.plist`](contrib/launchd/io.github.willehrendreich.sagefs.plist) is a user agent, the macOS counterpart of the systemd unit. It runs `~/.dotnet/tools/sagefs --supervised`, starts it at login, and launchd restarts the supervisor if it crashes. `sagefs status` shows it, and its console output goes to `~/Library/Logs/sagefs/`. It sets `DOTNET_ROOT` to the folder that holds the real `dotnet` on your PATH, because launchd doesn't read your shell profile. If `dotnet` isn't on your PATH, or your macOS is older than 12.3 and has no `realpath`, the install stops and says so instead of writing a plist that can't start. It also sets `PATH` to the `PATH` of the shell you run the install in. Otherwise the daemon and everything it starts get launchd's default, `/usr/bin:/bin:/usr/sbin:/sbin`, and an `init.fsx` that runs `npm` (or a script that calls `dotnet`) can't find it. A `PATH` with a `|`, `&`, `<`, `\` or line break in it can't be copied into the plist, so the install stops instead. If you move or upgrade .NET to a different folder, or want the daemon to see a `PATH` change, such as a new tool or another node version from nvm, run the install again. `launchctl kickstart -k` doesn't reread the plist. The install unloads the old agent before it writes the new plist, because launchd keeps a loaded agent's settings until it is unloaded. The agent runs the daemon from `~/Library/Application Support/sagefs-daemon` for the same reason the Linux unit stays out of your home directory. launchd doesn't create a working directory, which is what the `mkdir` is for.
- The supervisor starts a new daemon whenever the old one is gone, so `sagefs stop` gets you a fresh one, and it says so (exit code 3). To stop the service, run `launchctl bootout gui/$(id -u)/io.github.willehrendreich.sagefs`. To restart it, say after `dotnet tool update --global SageFs`, run `launchctl kickstart -k gui/$(id -u)/io.github.willehrendreich.sagefs`.
- ### Uninstall
- `sagefs uninstall` lists what SageFs left on this machine (a running daemon, the systemd unit and its drop-in or the launchd agent, the agent skill, the data and log folders) and prints the command that removes each, ending with `dotnet tool uninstall --global SageFs`. It changes nothing unless asked: `--remove-service` removes the unit or agent, `--stop` stops the daemon and its FSI workers, and `--purge-data --yes` (both flags) deletes the skill and the data folders. The full list of folders is in [Troubleshooting](docs/TROUBLESHOOTING.md#uninstall-and-where-sagefs-keeps-things).
- ### 4. Connect your editor
- **VS Code**: Install **SageFs** from the [Marketplace](https://marketplace.visualstudio.com/items?itemName=willehrendreich.sagefs) or [Open VSX](https://open-vsx.org/extension/willehrendreich/sagefs) (or the `.vsix` from [Releases](https://github.com/WillEhrendreich/SageFs/releases)), open an F# file, and press `Alt+Enter` on any expression. The result appears inline.
- **Neovim**: Add `"WillEhrendreich/sagefs.nvim"` to your plugin manager. Press `Alt+Enter` to evaluate. See [Neovim setup](https://github.com/WillEhrendreich/sagefs.nvim).
- **Web dashboard**: Open `http://localhost:37750/dashboard` for session management, evaluation, output, test state, and diagnostics without an editor extension.
- **AI agent** (Claude Code, Copilot, Codex, Cursor, anything that speaks MCP): `claude mcp add sagefs -- sagefs mcp` (or your client's equivalent for a stdio server). It starts the daemon for you if one isn't already running, so there's no ordering to get wrong. A daemon started that way lives as long as that agent session does. Start `sagefs` yourself first (or run it as a [service](#run-it-as-a-service-linux)) if you want it to stick around. `claude mcp add` defaults to local scope, meaning this project only. `--scope user` (`-s user`) gets it everywhere: `claude mcp add --scope user sagefs -- sagefs mcp`. `sagefs setup` prints the registration for each client it finds (Claude Code, VS Code, Cursor, Claude Desktop), and `sagefs setup --write` merges it into the client's config; the snippets and why an HTTP registration loses its tools are in [docs/client-setup.md](docs/client-setup.md). **Then install the [SageFs skill](skills/sagefs/SKILL.md)**. Without the skill your agent will iterate with `dotnet build` and never touch the REPL. [docs/agents.md](docs/agents.md) has the one-line install, an `AGENTS.md` snippet for other agents, and what to do when an agent drifts. Clients that only speak HTTP can still point at `http://localhost:37749/`, see [docs/mcp-tools.md](docs/mcp-tools.md#connect).
- ### 5. Enable live testing
- > **Live testing runs as you type.** SageFs evals your edited buffer into the session and re-runs only the *affected* tests against the new code. An unsaved edit flips a failing test red and back to green when you fix it, without ever touching the file on disk. Results stream inline with source-mapped test marks and coverage. Expecto is the framework that has been driven end to end: the repo has Expecto samples, and host-tier tests call `run_tests` against Expecto projects through a real MCP client. xUnit v2 and v3, NUnit, MSTest and TUnit are supported by one attribute-based path that finds a test by its attribute name and runs it by reflection. That path is tested against made-up attributes and a made-up test class, and the catalogue of attribute names and package markers for each framework is tested as data (`TestProviderCatalogTests`, `LiveTestingCoreTests`). No test or sample runs a real xUnit, NUnit, MSTest or TUnit assembly yet, so for those four, treat "discover, run and report" as expected to work and unproven.
- When live testing is enabled and a project is loaded, edits (saved or unsaved) re-run the affected tests automatically and update the marks. The engine, SSE events, coverage, and editor integrations work today across VS Code and Neovim. [Live testing without an agent](docs/live-testing-without-an-agent.md) takes you from a fresh install to red and green in your editor, and says how to turn it on in VS Code, Neovim, the dashboard and over HTTP.
- ### 6. What you'll see
- - **Test marks**: ✓ green (passing), ✗ red (failing), ● while it runs. In VS Code the mark sits at the end of the test's line and in the scrollbar's overview ruler, there is no icon in the gutter. In Neovim it is a sign in the sign column.
- - **Inline results**: Expression values appear to the right of your code
- - **Coverage marks**: In VS Code a small colored `│` (or `▸` and `○` for the per-test view) is drawn as text in front of the code, green for covered by passing tests, red when a covering test fails, gray for no coverage. Neovim puts coverage in the sign column.
- - **Failure details**: Hover over red markers to see Expected vs Actual diffs
- > 💡 **Tip**: Use the **SageFs: Run All Tests** 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](#coming-from-another-language): each one maps concepts you already know to F#, with runnable examples.
- <details>
- <summary>Build from source</summary>
- ```bash
- 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>
- 📚 **[Documentation](https://sagetech.dev/sagefs)** at sagetech.dev/sagefs.
- 📁 **[Docs in this repo](docs/README.md)**: the same guides and technical reference, alongside the code.
- ---
- ## Three Workflows: REPL, Live Testing, and Hot Reload
- > 📖 **[Full guide: Understanding Workflow Modes](docs/workflow-modes.md)**: decision tree, diagrams, real-world scenarios, troubleshooting, and how the Live Testing *workflow* differs from the live-testing *toggle*.
- A session runs in exactly one workflow, and the set is closed: [`SessionWorkflow`](SageFs.Core/WorkflowTypes.fs) is `Interactive | LiveTesting | HotReload`. The tradeoff between the first two and the third comes from a physical constraint of the .NET runtime. I didn't build it that way just to be difficult.
- **REPL** (`Interactive`, the 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 Testing** (`LiveTesting`) is the same full REPL, plus SageFs turns live testing on for you the moment the session is ready, and affected tests re-run on debounced keystrokes rather than on save. Pick it when you're doing TDD and want the test loop running without arming it by hand.
- **Hot Reload** (`HotReload`, also spelled `live` / `weblive` / `web` on the command line) enables browser hot reload. Save a `.fs` file and connected browsers update 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 Testing | Hot Reload |
- |:---|:---|:---|:---|
- | **Type redefinition** | Full, redefine types freely | Full | FS0037, expression-level changes only |
- | **Browser hot reload** | Manual refresh required | Manual refresh required | Yes, see [docs/hot-reload.md](docs/hot-reload.md) for which code shapes patch and which need a restart |
- | **Live testing** | Available, you turn it on | On automatically when the session is ready | Available, you turn it on |
- | **Best for** | Prototyping, domain modeling, exploration | TDD, red-green loops | Web apps with Falco, Datastar, ASP.NET |
- Live testing is *also* a per-session toggle that works in any of the three workflows (`POST /api/live-testing/enable`, or your editor's Enable Live Testing command). The `LiveTesting` workflow is the shortcut that arms it for you and drives it from keystrokes instead of saves. So "which workflow" and "is live testing on" are two different questions.
- ### Choosing the right workflow
- - **Building a web app** with Falco.Datastar, Giraffe, or any ASP.NET pipeline? Use **Hot Reload**. You want save-and-see-it feedback in the browser.
- - **Writing tests first?** Use **Live Testing**. The loop is armed for you and runs as you type.
- - **Exploring types**, designing domain models, or working in `.fsx` scripts? Use **REPL**. You need the freedom to reshape types as you go.
- - **Not sure?** Start with REPL. Switch when you need the browser or the test loop.
- ### Switching workflows
- Use your editor's command to switch workflows:
- - **Neovim**: `:SageFsWorkflow [name]` with `interactive`, `livetesting` or `hotreload`. With no name it opens a picker. It restarts the same session id in place, like VS Code and the dashboard.
- - **VS Code**: Command Palette → `SageFs: Switch Workflow`. This hits `POST /api/sessions/{sid}/workflow` directly, which restarts the same session id in place.
- - **MCP**: `switch_workflow` with `target` = `repl` | `livetesting` | `live` (⚠️ `live` means Hot Reload, not live testing; the alias predates the third workflow). This one creates a *new* session in the target workflow and stops the old one.
- - **Web dashboard**: a real dropdown next to your session, not a read-only badge. Pick a workflow and it switches, restarting the same session id in place, same as VS Code.
- VS Code and the dashboard swap the worker under your existing session id (spawn-first, so there's no dead window while it happens); the MCP tool spins up a fresh session and retires the old one. Either way, REPL-defined bindings are lost on the switch. Persisted files are unaffected.
- ### Auto-detection
- When SageFs detects web-oriented packages in your project (Falco.Datastar, Giraffe, Saturn, etc.), it suggests switching to the Hot Reload workflow. It's a suggestion in the tool's response text. SageFs never switches on its own.
- ---
- ## How SageFs Works
- SageFs has exactly **three concepts**: a daemon, sessions, and clients.
- ```mermaid
- 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 --- 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 AI fill:#1a1b26,stroke:#bb9af7,color:#c0caf5
- ```
- **The daemon is a service.** It starts with no project and no session. It just listens, and clients tell it what to do.
- **Sessions are isolated workers.** Each session is a separate OS process with its own FSI instance, project, and file watcher, so they can't interfere with each other. Create as many as you need. The watcher is rooted at the session's working directory, and a session opened in your home directory or a filesystem root is refused a watcher and says so in `/health` ([details](docs/multi-session.md#a-sessions-working-directory-is-its-file-watchers-root)). Open the session in the project directory.
- **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 and they all see the same state.
- | Capability | VS Code | Neovim | Web Dashboard | MCP |
- |:---|:---:|:---:|:---:|:---:|
- | Eval code / file / block | ✅ | ✅ | ✅ | ✅ |
- | Inline results | ✅ | ✅ | ✅ | ✅ |
- | Live diagnostics (SSE) | ✅ | ✅ | ✅ | ✅ |
- | Hot reload controls | ✅ | ✅ | ✅ | ✅ |
- | Session management | ✅ | ✅ | ✅ | ✅ |
- | Code completion | ✅ | ✅ | no | HTTP |
- | CodeLens | ✅ | ✅ | no | no |
- | **Live test marks** | ✅ | ✅ | no | no |
- | **Coverage marks** | ✅ | ✅ | no | no |
- | **Failure narratives** | ✅ | ✅ | ✅ | ✅ |
- | **Test source-jump** | ✅ | ✅ | no | no |
- | **Debug a failing test** | ✅ | ✅ | no | no |
- | Test panel | ✅ | ✅ | ✅ | ✅ |
- | Test policy controls | ✅ | ✅ | ✅ | HTTP |
- | Type explorer | ✅ | ✅ | no | ✅ |
- | Tests covering a symbol | ✅ | ✅ | no | HTTP |
- | History browser | ✅ | ✅ | ✅ | ✅ |
- | Test trace | ✅ | ✅ | ✅ | no |
- A ✅ in the MCP column means a tool in the [74-tool surface](docs/mcp-tools.md) does it. `HTTP` means the editors reach it through a daemon route and no tool does, and `no` means nothing does. Four of the rows are not MCP tools at all, and I'd rather the table said so than claimed a tool that isn't there: completions are an FSharp.Compiler.Service feature the editors call over HTTP (`POST /api/completions`); the call graph is `GET /api/dependency-graph`, since the `plan_ripple` / `get_cell_dependencies` tools graph FSI *cells* rather than source symbols; run policy is `POST /api/live-testing/policy` only; and there is no test-trace tool. The type explorer used to be on that list. `list_members` now walks the same tree for an agent, one level per call, and the editors keep using their HTTP route. [`docs/LIVE_TESTING_GUIDE.md`](docs/LIVE_TESTING_GUIDE.md) says so in as many words. The columns other than MCP say what's wired, not what's tested: most of the editor-side rendering (gutters, CodeLens, decorations, tree views) currently has no automated coverage in either client.
- <details>
- <summary><strong>Editor setup guides</strong></summary>
- #### VS Code
- Install **SageFs** from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=willehrendreich.sagefs) or [Open VSX](https://open-vsx.org/extension/willehrendreich/sagefs), or the `.vsix` in [Releases](https://github.com/WillEhrendreich/SageFs/releases). Written in F# via [Fable](https://fable.io/), not TypeScript.
- Current wiring includes Alt+Enter eval, CodeLens, live test decorations, native Test Explorer integration, hot reload sidebar, session context, type explorer, tests covering a symbol, event history, dashboard webview, status bar, auto-start, Ionide command hijacking, coverage marks, inline failure decorations, failure narrative enrichment, and test source-jump.
- #### Neovim
- [**sagefs.nvim**](https://github.com/WillEhrendreich/sagefs.nvim) lives in its own repository, and its README has the current command and keymap lists. I took the module, command and test counts out of this page because nothing in this repo checks them.
- ```lua
- -- 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, tests covering a symbol, 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.
- #### AI Agent (MCP)
- SageFs exposes 74 MCP tools, from `send_fsharp_code` to `targeted_verify` to `list_tests`. All of them are listed all the time (a member token is shown only what its role allows); calling one that doesn't apply to the current session state gets rejected with a structured error rather than being hidden. `get_daemon_status` reports daemon health, and `get_session_status` reports the selected session and its available tools. Any MCP client can connect. See the [full MCP Tools Reference](docs/mcp-tools.md) for the complete list and per-client configuration examples.
- **Streamable HTTP** (recommended: auto-reconnects, no session drops):
- ```json
- { "mcpServers": { "sagefs": { "type": "streamable-http", "url": "http://localhost:37749/" } } }
- ```
- **SSE** (legacy clients that don't support Streamable HTTP yet):
- ```json
- { "mcpServers": { "sagefs": { "type": "sse", "url": "http://localhost:37749/sse" } } }
- ```
- **OpenCode**: Add to `~/.opencode.json`:
- ```json
- {
- "mcp": {
- "sagefs": {
- "type": "remote",
- "url": "http://localhost:37749/sse",
- "enabled": true
- }
- }
- }
- ```
- #### Web Dashboard / Jupyter
- ```bash
- sagefs --jupyter conn.json # Run as a Jupyter kernel (experimental)
- # Dashboard auto-starts at http://localhost:37750/dashboard
- ```
- > **The Jupyter kernel is experimental.** Its wire-protocol message shapes and HMAC signing are unit-tested, but nothing in the suite opens a ZMQ socket or launches `sagefs --jupyter`, so the transport (`SageFs/JupyterTransport.fs`, NetMQ) is unproven end to end. The dashboard isn't experimental: it has real browser journeys in CI.
- </details>
- ---
- ## ⌨️ Keybindings Across Editors
- | Action | VS Code | Neovim |
- |--------|---------|--------|
- | Evaluate selection/cell | `Alt+Enter` | `<M-CR>` (or `<leader>re`) |
- | Evaluate entire file | `Alt+Shift+Enter` | `<leader>rf` |
- | Cancel evaluation | `Ctrl+Shift+C` | `<leader>rx` |
- | Clear inline results | Command Palette | `<leader>rc` |
- | Run all tests | Command Palette | `<leader>rT` |
- | Toggle test panel | Command Palette | `:SageFsTestPanel` |
- | Jump to test source | Click test in explorer | `<CR>` in telescope |
- | Show failure narrative | Hover on red marker | `<C-d>` in test panel |
- | Session picker | Command Palette | `<leader>rs` |
- > **Full keybinding references**: [VS Code](sagefs-vscode/README.md) · [Neovim](https://github.com/WillEhrendreich/sagefs.nvim#keymaps). The Neovim plugin lives in its own repository, so this table is a copy. Its keymaps are authoritative there, and nothing in this repo verifies them. (Neovim maps everything under `<leader>r`, not `<leader>s`, which LazyVim reserves for Search.)
- ---
- ## 🎨 Test and coverage marks
- Neovim draws these as signs in the sign column. VS Code draws the test marks (✓ ✗ ●) at the end of the test's line and in the scrollbar's overview ruler, and the coverage marks as text in front of the code. The only icon VS Code puts in the gutter itself is its own Test Explorer run and debug glyph, which comes from the **SageFs Live Tests** controller.
- | Mark | 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 a mark for details. In Neovim, press `<C-d>` on a failing test for the full failure narrative.
- >
- > 🐛 **In VS Code, a failing test has a Debug lens and a Debug link in its hover**, and the Test Explorer has Debug Test. It attaches the C# extension's .NET debugger to the process that runs your tests, so breakpoints bind in your compiled project code. Code you evaluated in the session has no debug symbols, so breakpoints in it will not bind. [How it works and what it needs](docs/LIVE_TESTING_GUIDE.md#debugging-a-failing-test).
- ---
- ## Live Testing Cost Comparison
- Visual Studio Enterprise has Live Unit Testing for C#. It costs about $250/month per seat, it only works in Visual Studio on Windows, and it supports xUnit, NUnit and MSTest. It copies your repo to a private workspace and runs MSBuild on it for every change ([Microsoft's description](https://learn.microsoft.com/en-us/visualstudio/test/live-unit-testing?view=vs-2022)). Its pages don't mention F#.
- SageFs delivers that loop with a REPL-centered architecture, and goes past it: an unsaved edit evals into the session and re-runs only the *affected* tests against your new code. No save, no copy of your repo, no MSBuild rebuild in the loop. Editors post the live buffer to `POST /api/sessions/{sid}/buffer-changed`; that endpoint has an integration test of its own, and the actual "an unsaved edit overrides the test a saved build already registered" behavior is proven at the worker level too (`WorkerLiveTestEvalTests.fs`), so the unsaved path is wired and covered. SageFs is F#-first and works across VS Code and Neovim. Client polish still varies, but the engine, SSE, and coverage are solid.
- | | VS Enterprise Live Testing | **SageFs** |
- |:---|:---|:---|
- | **How an edit is checked** | A private copy of the repo, built with MSBuild | **Your unsaved buffer is type-checked and evaluated in the FSI session that already has your project loaded.** No copy, no MSBuild rebuild. Measured through the real daemon on the small F# sample: a verdict on the edited function's test arrives about 0.7 s after the edit leaves the client (p50 712 ms, p95 783 ms over 20 edits), and a save is back to all green in about 0.5 s (p50 542 ms, p95 631 ms over 20 saves of a fresh session), on a 16-thread Ryzen 7 5800XT running Linux. That is one machine and one small project, see the pipeline note below |
- | **Which tests cover a line** | Per-line glyphs. Hover for how many tests hit the line, select the glyph for the tests by name ([Microsoft](https://learn.microsoft.com/en-us/visualstudio/test/live-unit-testing?view=vs-2022)) | **Per-line, with the exact tests whose own recorded coverage reaches it.** Tests of an instrumented project run one at a time to make that true. Visual Studio runs the tests in each assembly one after another too, per the same page |
- | **What a result ran against** | A real build of your solution | **Each row says: evaluated code, a real build, a real build that agreed, or a real build that disagreed and why.** A real build of the saved text confirms the eval once editing goes quiet; an unsaved buffer stays evaluated |
- | **Debugging a failure** | The glyph's tooltip debugs the set of tests, or only the ones you select | **VS Code: a failing test's Debug lens, hover link and Test Explorer profile attach a .NET debugger. Neovim: `:SageFsDebugTest` does the same through nvim-dap and netcoredbg.** One test at a time, and breakpoints don't bind in code the session evaluated. Still open ([roadmap](docs/roadmap.md)): a full attach run in our own tests, and a debug run doesn't update the gutter |
- | **Pause and scope** | Pause, also on build, debug and low battery. A playlist edited from the tool window or a right-click. A memory cap | **Pause, and an include or exclude set by name pattern.** No battery or debugger detection, no memory cap, no right-click include. [Why](docs/decisions.md#pause-and-an-include-or-exclude-set-are-enough-memory-caps-and-battery-detection-are-not-copied) |
- | **Code that doesn't compile** | Build errors go to the Output window | **Nothing is evaluated or run and your last results stay, marked as blocked, with the file and error count.** Tree-sitter still finds where your tests are in broken code |
- | **Why those tests ran** | Impacted tests are detected, the mechanism isn't documented | **Every selection says why** (exact dependency match, coverage approximation, fallback) and a failure says how long ago it last passed and what changed |
- | **Editors** | Visual Studio only | **VS Code · Neovim · Web dashboard · MCP clients** |
- | **Frameworks** | MSTest · xUnit · NUnit | **Expecto** is driven end to end. xUnit v2 and v3, NUnit, MSTest and TUnit share one attribute path that no real assembly has exercised yet ([details](#5-enable-live-testing)) · extensible |
- | **Price** | ~$250/month | **Free, MIT licensed** |
- Where Visual Studio is still ahead: it debugs several tests at once, it runs every result against a real build (mine confirms after two quiet seconds, and never for an unsaved buffer), it pauses on battery and while you debug, it has a memory cap and a right-click playlist, and it has been shipping since 2017. The plan for each, or the reason I didn't copy it, is in [how live testing works](docs/how-live-testing-works.md#compared-with-visual-studio-live-unit-testing), and what's queued is on the [roadmap](docs/roadmap.md).
- <details>
- <summary><strong>Three-speed feedback pipeline: how the sub-second path works</strong></summary>
- <br />
- 1. **Tree-sitter** detects test attributes in broken/incomplete code → immediate gutter markers
- 2. **F# Compiler Service** type-checks → dependency graph, reachability annotations
- 3. **Affected-test execution** via hot-eval → ✓/✗ results inline
- Each stage is progressively slower and progressively more certain, so you get a marker before you get a verdict.
- What's measured is the end-to-end path rather than the individual stages. The `--integration-lt` tier starts a daemon, opens the FromCSharp sample, and times keystroke-to-verdict and save-to-green over 20 edits each after 2 warm-up edits (the figures are in the table above, with the machine they came from), and it fails if the 95th percentile passes 3 s. Those figures say nothing about a large solution. There is one real, currently-enforced millisecond budget on pure logic: `CoverageViewTests.fs`'s "hot path is tight" test asserts 100 coverage-view projections over 200 tests complete in under 100ms, and it runs in the default suite, not gated behind anything. `LiveTestingCycleTests.fs` has a second one (`cycleBenchmarkTests`, `[Benchmark]`-tagged) that the default suite filters out and no CI stage runs. Both measure pure decision functions (no FSI, no compiler, no real test execution in the loop), so treat them as a floor on the domain logic, not a promise about wall-clock save-to-green latency. Any *end-to-end* speed number you see about SageFs is an anecdote until something gates it.
- Tests are automatically categorized (Unit, Integration, Browser, Property, Benchmark, Architecture), each with its own run policy: unit and property tests run automatically by default, integration/browser/architecture run on demand by default, and benchmarks stay disabled until you turn them on. All of this is configurable. SageFs's own suite leans hard on property-based testing: 1422 property-based tests exercise the binary format, state machines, and event folds against generated inputs (`grep -rho -E "\b[pf]?testProperty(WithConfig)?\b" SageFs.Tests` across all `*.fs` files, the same regex `SageFs.Tests/TestCountBadge.fs` uses to restamp this line; restamp with `dotnet run --project SageFs.Tests -- --update-badge` rather than hand-editing it). That figure counts property declarations in the source, not test cases, and the grep gave 1422 on 2026-11-10. The `13067+` badge at the top counts runnable cases in the default suite. It was last stamped on 2026-10-05 (`6e91ecd2`), 946 commits ago, and nothing re-derives it on its own, so it is out of date until someone runs the restamp.
- </details>
- ---
- ## Under the Hood
- **Hot Reload**: File changes are detected, the changed functions are re-emitted into FSI, and [Harmony](https://github.com/pardeike/Harmony) re-points those method pointers at runtime. Connected browsers auto-refresh via SSE. [Which shapes patch, and which need a restart →](docs/hot-reload.md)
- **Multi-Session**: Run multiple isolated F# sessions simultaneously, each in its own worker sub-process with independent FSI, project, and file watcher. [Full details →](docs/multi-session.md)
- **MCP Tools**: 74 tools for session trust, code execution, running and listing tests, verification, failure explanation, analysis, local friction reporting, leases for expensive work, workspace hygiene, and coordinating several agents on one repo. They're affordance-gated at call time: the list is complete unless you start the daemon with `SAGEFS_TOOL_LIST=Starter` (nine tools for a first session, every other tool still callable by name), and a call to a tool that doesn't apply to the current session state is rejected with a structured error. [Full reference →](docs/mcp-tools.md)
- **SSE Events**: All editors receive `test_source_locations`, `file_annotations`, and `failure_narratives` events tagged with `SessionId`. [Full reference →](docs/sse-events.md)
- **Architecture**: Daemon-first design with isolated worker sub-processes, a web dashboard, editor integrations, and an affordance-driven MCP surface. [Full details →](docs/architecture.md)
- ### Repository Map: where things live
- - `SageFs.Core/`, the shared engine and runtime logic: session management, MCP/session operations, live testing, persistence, and shared rendering primitives
- - `SageFs/`, the CLI entrypoint, daemon host, MCP server, dashboard, and worker HTTP transport
- - `SageFs.Host/`, the worker process the daemon spawns per session: it loads your project with MSBuild, shadow-copies and instruments the outputs for coverage, and runs the worker HTTP transport the daemon talks to. It never runs your code
- - `SageFs.FsiHost/`, the isolated FSI host, built and launched per session by `SageFs.Core/IsolatedFsiSession.fs`. Sessions run in it by default. It holds the FSI session and your running code, the hot-reload detours and the live-testing agent. Its dependency closure is deliberately tiny (the SDK's own FSharp.Core and F# compiler, a renamed copy of Harmony, and about thirty of our own source files compiled in), and it references none of SageFs's assemblies, so a project's own dependency versions never collide with the daemon's. [How that works](docs/how-isolation-works.md)
- - `SageFs.Simulation/`, deterministic simulation (DST) models that fold the real cores: file-reload routing, worker lifecycle, supervision, the manifest
- - `SageFs.Tests/`, the Expecto suite: unit tests, property tests, snapshot tests, the DST drivers, and every real-daemon integration and browser journey
- - `sagefs-vscode/`, VS Code extension (F# via Fable → JavaScript)
- - `docs/`, user docs, architecture notes, troubleshooting, and feature references
- - `quality/`, the release Definition-of-Done matrix the publish workflow gates on
- - `samples/`, runnable sample apps and language-onramp projects
- - `scripts/`, repo helper scripts and smoke/integration utilities
- - `ci-pipeline.fsx`, CI is one Partas.Build pipeline; the GitHub workflows just invoke it
- `SageFs.slnx` has `SageFs.Core`, `SageFs.Simulation`, `SageFs`, `SageFs.Host`, `SageFs.Tests` and the samples. It has no legacy projects, and `SageFs.FsiHost/` is built per session by the tool, not by the solution. The VS Code integration lives alongside it in `sagefs-vscode/` because it uses its own packaging toolchain and release flow.
- The Neovim plugin isn't in this repo. It lives in the separate [`sagefs.nvim`](https://github.com/WillEhrendreich/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`
- - Neovim client wiring: the separate `sagefs.nvim` repo
- <details>
- <summary><strong>🛡️ Supervised Mode: restart automatically on crash</strong></summary>
- <br />
- ```bash
- sagefs --supervised
- ```
- Erlang-style supervisor with exponential backoff (1s → 2s → 4s → max 30s, each delay shortened by a random amount of up to half so several daemons don't retry in step). After 5 restarts inside 5 minutes it gives up and reports the failure. A crash within 10 seconds of the last restart is treated as a startup crash: it backs off four times as long and the ceiling drops to 3, because a daemon that can't come up is almost always a config problem. 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>⚡ Spawn-First Restart: no dead window on hard reset</strong></summary>
- <br />
- A hard reset spawns the replacement worker *first* and only retires the old one once the new one is ready, so the session is never left without a live worker mid-swap. (`rebuild=true` still runs a `dotnet build` before the swap; `rebuild=false` reuses the current build.)
- One case goes the other way round. A session with a startup profile (`.SageFs/init.fsx`, or a `.SageFsrc`) may start an app on a fixed port at load, and the old worker still holds that port while the replacement loads the profile. So for those sessions the old worker leaves first, and the replacement starts once it is gone. The session shows `Restarting` for that stretch, and `get_session_status` with `wait_seconds` waits it out. The profile is looked for where the worker looks: the folder of the first project it loaded (for a solution, the first project of the solution, as the worker reports it), then the working directory.
- </details>
- <details>
- <summary><strong>💾 Binary Persistence: instant resume</strong></summary>
- <br />
- SageFs persists the daemon's session registry and per-session test caches to compact binary files for near-instant cold starts. The files are raw binary with CRC-32C integrity checking, no JSON parsing and no database.
- - **Daemon manifest** (`.sagefm`, v1): the durable session registry (which sessions existed, their projects, and working directories, plus which was active), replayed on startup to rebuild your sessions.
- - **Test cache files** (`.sagetc`, written as format version 3): test outcomes and durations, each test's coverage bitmap, and the flaky-detection history. [The format](docs/binary-format-spec.md#3-sagetc-test-cache-format) is written down next to the code that reads it.
- Design: length-prefixed strings, section headers with byte-count envelopes, version negotiation, and field-level bounds checking prevent OOM from crafted inputs. The formats are verified by property-based tests covering format corruption, round-trips, and write isolation.
- </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 --jupyter <conn.json> Run as Jupyter kernel
- sagefs mcp Speak MCP over stdio (spawns the daemon if needed)
- sagefs check Check environment before first run
- sagefs stop Stop running daemon
- sagefs status Show daemon info
- sagefs sweep [--kill] Reap daemons whose owner process is gone
- sagefs hygiene [--tidy] Show what agents left behind (worktrees, gate checkouts, caches, temp dirs) as a dry-run plan; --tidy runs only the safe part
- (--repo PATH names a repository you are not standing in)
- sagefs play <ledger.jsonl> Replay a portable cohort ledger file offline
- sagefs cohort-export [--scope <path>] [--data-dir <dir>] <out.jsonl>
- Write the daemon's cohort ledger to a file `play` can replay (offline, no daemon needed)
- Daemon options:
- --no-resume Skip restoring previous sessions on startup
- --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 dashboard runs on this port + 1.
- A port other than the default needs --owner-pid or --ttl.
- --owner-pid PID Exit when the process at PID exits. For a daemon an agent,
- test or demo spawns. (--owner-start TICKS closes the pid-reuse race.)
- --ttl DURATION Self-terminate after DURATION (e.g. 30m, 1h, 90s) with no
- live sessions and no MCP/SSE clients.
- A value that is not valid (--ttl 30min) stops the daemon at
- start with exit code 2; it never starts unowned.
- ```
- 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`, evaluated as real F# by an isolated FSI host, never by the daemon itself ([`SageFs.Core/ConfigHost.fs`](SageFs.Core/ConfigHost.fs)):
- ```fsharp
- { DirectoryConfig.empty with
- Load = Projects ["src/MyApp.fsproj"; "tests/MyApp.Tests.fsproj"]
- AutoOpenNamespaces = false }
- ```
- The `DirectoryConfig` record has seven fields ([`SageFs.Core/DirectoryConfigTypes.fs`](SageFs.Core/DirectoryConfigTypes.fs)): `Load`, `AutoOpenNamespaces`, `ValueWalk`, `DefaultArgs`, `Gc`, `SessionEnv` and `Artifacts`. Each one is read by something. `InitScript`, `IsRoot` and `SessionName` were removed on 2026-11-07 because nothing read them: a config that set one was accepted and ignored, which is worse than an error. A config file that still names one now fails to evaluate, and the daemon log says which field.
- - `AutoOpenNamespaces = false` skips warmup auto-opening of namespaces and modules. Both places the daemon creates a session read it ([`SageFs/DaemonMode.fs`](SageFs/DaemonMode.fs)), so it holds whichever client made the session.
- - `Load` picks which projects or solution a session loads, but **only the web dashboard's own Create-session flow reads it** ([`SageFs/DashboardTypes.fs`](SageFs/DashboardTypes.fs)). MCP and the editor HTTP API take an explicit project, solution, or bare target and never consult this file, so `Load` has no effect on sessions created from an editor or an agent.
- - `ValueWalk = WalkSafe | WalkEverything | WalkOff` sets how much of a value the live-bindings pane may run to show it, for new sessions. It defaults to `WalkSafe`, and the daemon reads it when it starts a session's pane ([`SageFs/DaemonMode.fs`](SageFs/DaemonMode.fs)). [`docs/sse-events.md`](docs/sse-events.md) says what each mode does.
- - `DefaultArgs` are extra arguments for the session's FSI host (`DefaultArgs = ["--no-warn:1182"]`), added after the ones SageFs builds. Every client's sessions get them: the daemon reads the config when the session is created and hands the result to the worker, so reading a config for any other reason (a page, a status) changes nothing a session uses.
- - `Gc = ServerGc` starts the session's FSI host under Server GC (`DOTNET_gcServer=1`), so code you time in the REPL runs under the collector it will really run with. `WorkstationGc` is the default. Server GC commits a heap per core, so it stays opt-in.
- - `Artifacts = ArtifactsIn "/abs/dir"` moves `bin` and `obj` of the session's own builds there (MSBuild's `ArtifactsPath`), so nothing is written under the project. The daemon's builds, the worker's rebuilds and the project loader all use it. The path must be absolute; an empty one, a relative one or one under `/proc` is refused with the reason and the project builds where it always did. A project that sets `ArtifactsPath` in its own build files keeps its choice, and the session's request is refused with a message naming both folders ([who wins, and why](docs/configuration.md#session-options-garbage-collector-environment-and-artifacts-folder)).
- - `SessionEnv = [ EnvEntry("NAME", "value") ]` sets environment variables for that session's host and nothing else. A name SageFs removes from every process it starts (`DOTNET_ROOT`, `MSBUILD_EXE_PATH` and the others in [`ProcessEnvironment.poisonedVariables`](SageFs.Core/ProcessEnvironment.fs)) is refused with the reason, and a name SageFs sets itself keeps SageFs's value and is reported in the log.
- `Gc`, `SessionEnv` and `Artifacts` also have rows in the dashboard's Settings page (the "Session" group), saved per directory, and a field in `config.fsx` wins over its row. A session keeps the options it started with: creating another session in the same directory later does not change it. [`docs/configuration.md`](docs/configuration.md#session-options-garbage-collector-environment-and-artifacts-folder) has the details.
- Built-in ways to create or edit the auto-open setting:
- - **Dashboard**: the small circle icon on a session card (green `◎` is on, red `◌` is off). Click it to flip the setting for that session's directory; the tooltip says which way it will go.
- - **VS Code**: run **SageFs: Configure Warmup Auto-Open**
- - **Neovim**: run `:SageFsConfig`
- If `.SageFs/config.fsx` doesn't exist, these affordances create it with:
- ```fsharp
- { 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**: the prelude. It is a file SageFs finds by name, and no config field names it. It is not global. At the end of a session's warmup, SageFs looks for `.SageFs/init.fsx` or `.SageFsrc` in the folder of the first project the session loads, then **in that session's own working directory**, the folder its `.SageFs/config.fsx` is read from. It evaluates the first one it finds ([`SageFs.Core/StartupProfile.fs`](SageFs.Core/StartupProfile.fs)). So a session opened in `site/` with `Dev/Dev.fsproj` reads `site/Dev/.SageFs/init.fsx` if it exists, and `site/.SageFs/init.fsx` if not. Only one script runs. Relative `#load` and `#r` paths in it resolve against the project's folder (`site/Dev/`). A script found in the working directory can also use paths relative to that folder (`site/`); FSI tries the project's folder first. There is no `~/.SageFs/init.fsx` home-directory startup profile; no code path looks there.
- **Precedence:** Inside the dashboard's Create-session flow only: an explicit project list you type wins, then `.SageFs/config.fsx`'s `Load`, then auto-discovery from the working directory. MCP and the HTTP API (VS Code, Neovim) don't read the config file on session creation at all, so there's no precedence to speak of there. Whatever project list the client sends is used as-is.
- </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` |
- | Results don't match the code you just wrote, or a "type not found, Version=…" / "Could not load file or assembly 'System.Runtime, Version=…'" error | Your daemon is older than your code and is still serving what it started with. `sagefs status` to see its version, then `dotnet tool update --global SageFs` and restart it. |
- | Port already in use | `sagefs stop`, or set `SAGEFS_MCP_PORT=8080` for the daemon you want to keep. `--mcp-port 8080` alone is refused: a daemon off the default port has to say who owns it with `--owner-pid` or when to give up with `--ttl` |
- | 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. |
- | Session stuck warming up on a big repo | Name one project or solution, or choose a bare session explicitly. SageFs builds missing generated state itself. See [Large repos](docs/TROUBLESHOOTING.md#warmup-progress-phases) |
- 📖 **[Full Troubleshooting Guide →](docs/TROUBLESHOOTING.md)**: covers first-run issues, runtime problems, where the logs are, what a Degraded health reading means, platform-specific fixes, and diagnostic tools.
- ⚙️ **[Configuration →](docs/configuration.md)**: every `SAGEFS_*` environment variable, with its default and what it is for.
- 📊 **[Feature Matrix →](docs/FEATURE_MATRIX.md)**: compare features across VS Code, Neovim, the web dashboard, and MCP.
- ---
- ## Coming from Another Language?
- You don't need to know F# already. Find your background below for a guide that maps concepts you know to F#, with runnable examples.
- > **Quick orientation:** Every sample in [`/samples`](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.
- | Background | One-liner | Guide |
- |:---|:---|:---|
- | 🐍 **Python** | Same REPL energy, plus a compiler that catches bugs before you run | [Guide →](docs/coming-from-python.md) |
- | 📓 **Jupyter** | Everything you love about notebooks, minus kernel crashes and JSON diffs | [Guide →](docs/coming-from-jupyter.md) |
- | 🔷 **C#** | Same .NET, same NuGet, stop writing `AbstractRepositoryFactoryImpl` | [Guide →](docs/coming-from-csharp.md) |
- | ☕ **Java** | Expressive, type-safe, concise, what Java always wished it could be | [Guide →](docs/coming-from-java.md) |
- | 🟨 **JS/TS** | No `undefined`, no `this` bugs, no `node_modules`, just functions | [Guide →](docs/coming-from-javascript.md) |
- | 🦀 **Rust** | `Option`, `Result`, pattern matching, without the borrow checker | [Guide →](docs/coming-from-rust.md) |
- | 🧘 **F# Koans** | You already know F#, now get instant feedback instead of `dotnet run` | [Guide →](docs/coming-from-koans.md) |
- ---
- ### 🎯 Visual Demos
- See what SageFs makes possible beyond the REPL:
- #### 🌐 Reactive Web App: Falco + Datastar, zero JavaScript
- A full CRUD todo app in about 100 lines of F#. Edit a handler and save, and the browser updates immediately: no webpack, no bundler, no framework setup.
- **→ [`samples/demos/webapp-datastar.fsx`](samples/demos/webapp-datastar.fsx)**
- > **The two Raylib demos below are unverified for hot reload.** Hot reload itself works (see [docs/hot-reload.md](docs/hot-reload.md)), but no automated test of any kind drives a Raylib window through a save, so the "updates live" claims here rest on nothing executable. I built them to show the shape of the thing, not as a proven guarantee. Treat them accordingly. The reload rules still apply, and one of them matters here: `starMaxSpeed`, `playerWidth` and `starColors` are plain `let` values, and a redefined value only takes effect when nothing in the running app kept a copy of the old one. A function that hands the value on (a frame loop passing it to Raylib, say) makes that save a restart, and the save says who kept it. See [Values](docs/hot-reload.md#values). I haven't run these demos through a save, so I don't know which of those two things you'll see.
- #### 🎨 GPU Window: Raylib Hello World with hot reload
- A Raylib window intended to hot-patch on save: change the color, the text, or the animation, save, and it should update in the running window, no restart, no flicker.
- **→ [`samples/demos/raylib-hello.fsx`](samples/demos/raylib-hello.fsx)**
- #### 🕹️ Interactive Game: live-tweakable physics
- A playable star-catcher game. Editing `starMaxSpeed`, `playerWidth`, and `starColors` in the source file and saving is meant to apply to the running game without interrupting play.
- **→ [`samples/demos/raylib-game.fsx`](samples/demos/raylib-game.fsx)**
- ---
- ## Contributing
- SageFs is open source, and contributions are welcome: bug fixes, documentation improvements, new tests, or whole features. PRs are encouraged.
- **→ [Read the Contributing Guide](CONTRIBUTING.md)** 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](LICENSE)
- ## Acknowledgments
- SageFs exists because of Jo Van Eyck's [fsi-mcp-server](https://github.com/jovaneyck/fsi-mcp-server), a minimal F# Interactive MCP server that proved the concept of connecting FSI to editors via MCP. That project made everything here possible.
- [FsiX](https://github.com/soweli-p/FsiX) · [sagefs.nvim](https://github.com/WillEhrendreich/sagefs.nvim) · [Falco](https://github.com/pimbrouwers/Falco) & [Falco.Datastar](https://github.com/spiraloss/Falco.Datastar) · [Harmony](https://github.com/pardeike/Harmony) · [Ionide.ProjInfo](https://github.com/ionide/proj-info/) · [Raylib-cs](https://github.com/ChrisDill/Raylib-cs) · [Fable](https://fable.io/) · [ModelContextProtocol](https://modelcontextprotocol.io/)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.