SageFs/docs.mdfsharplive

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 SageFs
  1. Install the .NET 10 SDK or the .NET 11 SDK if you haven't already.

  2. Install SageFS globally with the command above; no config files required.

  3. Verify your environment: sagefs check validates your SDK, FSI, project files, port, and daemon state.

  4. Start the daemon: sagefs. It starts the service and exposes the Web Dashboard while waiting for clients.

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

  1. Open any .fs or .fsx file in a connected editor.

  2. Send an expression to the engine: press Alt+Enter in Neovim or VS Code, or use the evaluator in the Web Dashboard.

  3. Read the result inline. Each ;; is a transaction: a failure discards that one statement and keeps everything before it.

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

A 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

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

CommandDescription
sagefsStart the daemon and Web Dashboard; wait for editor, MCP, or browser clients.
sagefs mcpSpeak MCP over stdio, starting the daemon first if it isn't running. The daemon it starts lives as long as the client does.
sagefs checkValidate SDK, FSI, project files, port, and daemon state.
sagefs statusShow daemon/port/session state.
sagefs stopStop 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 PORTMCP 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 PIDExit when the process at PID exits. For a daemon an agent, test or demo spawns.
sagefs --ttl DURATIONSelf-terminate after DURATION (30m, 1h, 90s) with no live sessions and no MCP or SSE clients.
sagefs --supervisedErlang-style watchdog with exponential backoff.
sagefs --no-resumeSkip restoring previous sessions on startup.
sagefs --pruneMark 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.

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.

Save to green: open full-screen (interactive: pan, zoom, focus, theme).

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
✗Failing
○No coverage

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.

MCP eval round-trip: open full-screen (interactive: pan, zoom, focus, theme).

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

ToolDescription
send_fsharp_codeExecute F# code. Each ;; is a transaction boundary.
check_fsharp_codeType-check a snippet without executing (current FSI context).
cancel_evalCancel a running evaluation.
get_session_statusSession health, loaded projects, and the tools available in the current state.
get_recent_fsi_eventsRecent evals, errors, and loads with timestamps.
run_appRun the session's executable project with hot reload (like dotnet run).
stop_appStop the app started by run_app; the session keeps running.
list_runnable_projectsList the session's projects and which ones run_app can run.

Sessions & Status

ToolDescription
get_available_projectsDiscover .fsproj/.sln/.slnx files.
create_project_sessionCreate an isolated FSI session for one explicit .fsproj.
list_sessionsList all active sessions.
switch_sessionSwitch active session.
switch_workflowSwitch between REPL, Live Testing, and Hot Reload workflows.
stop_sessionStop a session by ID.
reset_fsi_sessionSoft reset: clear definitions, keep DLLs.
hard_reset_fsi_sessionFull reset: rebuild, reload, fresh session.
enable_hot_reloadEnable file watching / hot reload for the session.
disable_hot_reloadDisable file watching / hot reload for the session.

Testing, Verification & Coverage

ToolDescription
list_testsList discovered tests, grouped by file with source locations.
run_testsRun 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_verifyPlan a trustworthy verification pass for one changed behavior; refuses to claim green on stale code.
explain_test_failureEnriched failure context for a test that recently went Passed→Failed.
diagnoseFull diagnostic report: test failures, cell staleness, ripple plan, suggestions.
coverage_intelAnalyze test coverage quality: blind spots, correlated failures.
impact_forecastForecast performance impact and downstream blast radius for cells.
suggest_next_actionPrioritized next-action queue combining coverage, impact, staleness.
suggest_next_cellType-directed suggestions for what to evaluate next, from bindings in scope.
suggest_repairGiven a failing test, trace causal changes and suggest the symbol to fix.
plan_ripplePlan cascade re-evaluation for changed cells using the dependency graph.
preview_what_ifPreview what would change if a binding had a different value, without executing.
decompose_pipelineDecompose an F# pipeline into stages with purity classification.
get_cell_dependenciesExpose the cell dependency graph with staleness annotations.
discover_featuresContext-aware feature discovery ranked by relevance.

Friction Telemetry (local)

ToolDescription
get_friction_summaryCompact summary of MCP friction (local).
get_friction_reportStructured JSON report of MCP pain points (local).
report_frictionRecord 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.

ToolDescription
join_cohortJoin the daemon's shared coordination session.
leave_cohortLeave; any claims you hold are orphaned for the conductor to reassign.
get_cohort_statusMembers, claims, the test matrix, and the landing queue.
acquire_claimTake an exclusive claim on a file or project so other agents know it's yours to edit.
release_claimRelease a claim you hold.
reassign_claimConductor-only: reassign an orphaned claim.
request_landingQueue a landing: your commits are rebased onto the integration head, verified, and fast-forwarded in, one at a time.
set_integration_refConductor-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

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.

:SageTech --ready