Documentation

Everything you need to know about installing, configuring, and using SageFs — the live F# development environment with instant feedback.

Installation

SageFs is distributed as a .NET global tool. You need the .NET 10 SDK installed.

dotnet tool install --global SageFs

Verify the installation:

SageFs --version

Quick Start

Start the daemon — it runs bare and waits for your editor to connect:

# Start the daemon (bare — no project flag needed)
SageFs

# Then create a session for your project from your editor, MCP client, or dashboard
# Example target: path/to/MyProject.fsproj

SageFs launches a daemon that listens for client connections. When your editor (Neovim, VS Code, Visual Studio) creates a session, the daemon auto-discovers your project, pre-compiles dependencies, and starts an interactive session. Hit Alt+Enter to evaluate code, or just save a file — the daemon watches for changes and hot-reloads automatically.

Startup Modes

SageFs operates in several modes depending on how you invoke it:

Subcommands

Source: SageFs/Program.fs

Flags

Source: SageFs.Core/Args.fs

Environment Variables

MCP — Model Context Protocol

SageFs exposes an MCP server that allows AI agents (Claude, GitHub Copilot, etc.) to interact with live F# sessions. The MCP server runs on port 37749 by default and serves tools over Server-Sent Events (SSE).

The available tools change based on session state — you can't evaluate code while the session is still warming up, for example. This is by design: it prevents race conditions and gives agents clear feedback about what's possible at any moment.

Source: SageFs.Core/Mcp.fs, SageFs.Core/Affordances.fs

MCP Tool Reference (30 tools)

Session State Machine

The MCP tools available to an agent depend on the session's current state. This prevents race conditions — you can't evaluate code while the session is still loading your project.

Daemon & Workers

SageFs uses a daemon + worker architecture. When you start SageFs, a single daemon process launches and manages everything: HTTP endpoints, SSE subscriptions, MCP server, session routing. Actual F# evaluation happens in separate worker processes — one per session.

Why separate processes?

• Crash isolation — a worker crash doesn't take down the daemon or other sessions
• DLL locking — each worker has its own assembly load context via shadow copying
• Parallelism — multiple sessions can evaluate code concurrently

Worker Protocol

The daemon communicates with workers over HTTP using a typed message protocol defined in WorkerProtocol.fs. Each message is a discriminated union case — evaluate, check types, get completions, reset, etc.

Standby Pool

To eliminate cold-start delays, the daemon maintains a standby pool of pre-warmed workers (StandbyPool.fs). When you reset a session, a warm standby swaps in instantly — your project is already compiled and loaded. The pool auto-replenishes when .fsproj changes are detected.

Crash Recovery

The Watchdog monitors every worker. If one crashes, it auto-restarts with exponential backoff. State is State is persisted to binary manifests (EventStore.fs), so a recovered session resumes where it left off.

Elm Architecture

All state management follows the Elm architecture (TEA — The Elm Architecture):

type Update = Msg → Model → Model * Effect list

Every event — keystrokes, file changes, test results, SSE messages, MCP requests — dispatches through a pure update function. No shared mutable state. No locks. Side effects execute after the model updates. The UI is always a pure function of the current model.

Key files:

• ElmLoop.fs — generic event loop implementation
• SageFsApp.fs — main app wiring: routes messages to features
• ElmDaemon.fs — daemon-mode loop with SSE and HTTP
• AppState.fs — the single immutable model record

Rendering Pipeline

SageFs has two UI frontends — a terminal TUI and a Raylib GPU GUI — that share the exact same rendering pipeline:

ElmModel → render → RenderRegion list → Screen.draw → Cell[,] → Backend.emit
                                                                   ├── AnsiEmitter (TUI)
                                                                   └── RaylibEmitter (GUI)

The shared Cell[,] grid is a 2D array of characters with colors and attributes. All layout, drawing, and pane composition happens at this abstract level (TerminalUI.fs). The TUI backend emits ANSI escape codes; the Raylib backend draws GPU quads. Same logic, pixel-perfect parity.

Live Testing

SageFs discovers and runs tests continuously as you code. The three-speed pipeline:

1. Discovery (~50ms) — TestTreeSitter.fs finds test functions using Tree-sitter, even in code that won't compile
2. Dependency Graph (~350ms) — the F# Compiler Service builds a graph of what changed and what depends on it
3. Execution — only affected tests run via LiveTestingExecutors.fs

Run Policies

Tests are categorized, and each category has a configurable run policy:

Hot Reload

When you save an .fs file, SageFs patches method pointers at runtime — no IL instrumentation, no process restart. Changed functions are live in ~100ms. The pipeline:

1. FileWatcher.fs detects the change
2. Only the changed file recompiles (F# Compiler Services incremental compilation)
3. HotReloading.fs patches the method table
4. Live testing pipeline re-runs affected tests
5. All connected editors receive updated results via SSE

Neovim Plugin

The Neovim plugin (sagefs.nvim) is a first-class client with 38 Lua modules and 1142 tests. It connects to the running daemon via SSE and provides:

• Cell evaluation — send code to the daemon with Alt+Enter
• Inline results — evaluation output displayed as virtual text next to your code
• Gutter signs — green/red marks for test pass/fail status on each line
• Live test panel — floating window showing all tests and their current state
• Coverage gutter — highlights which lines are exercised by passing tests
• Type explorer — browse .NET namespaces and types from within Neovim
• Session management — create, switch, reset sessions via commands
• Code completions — powered by the daemon's F# Compiler Services integration
• Daemon lifecycle — auto-detects or starts the daemon

VS Code Extension

The VS Code extension lives in sagefs-vscode/ and is written in F# compiled to JavaScript via Fable. It manages the daemon lifecycle and connects to it for real-time feedback.

Visual Studio Extension

The Visual Studio extension lives in sagefs-vs/. It uses the VS Extensibility SDK (net8.0-windows8.0) with a C# shim (SageFs.VisualStudio) and F# core logic (SageFs.VisualStudio.Core).

Built-in TUI

The default SageFs experience. A full-screen terminal interface with multiple panes: editor, output, sessions, tests, diagnostics, and a status bar showing frame time. Built on the shared Cell[,] rendering pipeline. Source: SageFs/TuiClient.fs.

Raylib GPU GUI

Same features as the TUI but rendered in a GPU-accelerated window using Raylib. Provides crisp font rendering and smooth scrolling. Lives in SageFs.Gui/. Launch with SageFs gui or SageFs --both to run TUI and GUI simultaneously.