FsHotWatch 0.3.0-alpha.1

FsHotWatch

Speed up your F# development feedback loop.

FsHotWatch is a background daemon that watches your source files and keeps the F# compiler warm. When you save a file, it instantly re-checks it and tells your tools (linters, analyzers, test runners) what changed — without restarting the compiler from scratch each time.

The problem

F# tools are slow because they each start their own compiler from zero. A 15-project solution takes ~2 minutes to analyze. Every time you save a file, your linter restarts, your analyzer restarts, your test runner restarts — all parsing and type-checking the same 500 files again.

How FsHotWatch helps

FsHotWatch runs one compiler in the background and shares it with all your tools:

1. You save a file — FsHotWatch notices the change
2. It re-checks just that file using the compiler that's already warm (milliseconds, not minutes)
3. Plugins get the results instantly — your linter, analyzer, and test runner all see the updated check results without re-parsing anything
4. You query the results — fs-hot-watch status shows what each tool found

Changes are debounced — if you save 10 files in quick succession (like a formatter running), FsHotWatch waits for things to settle, then processes them all in one batch.

Quick start

# Install the CLI tool
dotnet tool install -g FsHotWatch.Cli

# Start the daemon in your repo (runs in foreground, Ctrl+C to stop)
fs-hot-watch start

# From another terminal, check what's happening
fs-hot-watch status

Packages

FsHotWatch is split into small packages so you only install what you need:

Writing your own plugin

Plugins use a declarative framework: you define an update function that receives events and returns new state. The framework manages the agent, status tracking, and IPC command registration.

open FsHotWatch.Events
open FsHotWatch.PluginFramework

type MyState = { FilesChecked: int }

let myPlugin: PluginHandler<MyState, unit> =
    { Name = "my-plugin"
      Init = { FilesChecked = 0 }
      Update =
        fun ctx state event ->
            async {
                match event with
                | FileChecked result ->
                    // result.ParseResults and result.CheckResults come from
                    // the warm FSharpChecker — no re-parsing needed.
                    printfn "Checked: %s" result.File
                    ctx.ReportStatus(Completed(System.DateTime.UtcNow))
                    return { FilesChecked = state.FilesChecked + 1 }
                | _ -> return state
            }
      Commands =
        [ "my-status",
          fun state _args ->
              async { return $"checked %d{state.FilesChecked} files" } ]
      Subscriptions =
        { PluginSubscriptions.none with
            FileChecked = true }
      CacheKey = None }

// Register with the daemon:
daemon.RegisterHandler(myPlugin)

Available events (subscribe via Subscriptions):

• FileChanged — a source file was saved (you get the file paths)
• BuildCompleted — dotnet build finished (success or failure)
• FileChecked — a file was type-checked (you get parse + check results)
• TestCompleted — tests finished running (you get per-project results)

What you can do in Update via ctx:

• ctx.Checker — the warm FSharpChecker (reuse it for your own analysis)
• ctx.RepoRoot — path to the repository root
• ctx.ReportStatus(status) — tell the daemon your current status
• ctx.ReportErrors(file, entries) — report diagnostics to the error ledger
• ctx.EmitBuildCompleted(result) — emit events to other plugins
• ctx.Post(msg) — send a custom message back to your own agent

Configuration

Create .fs-hot-watch.json in your repo root. All fields are optional — sensible defaults are used when omitted.

{
  "build": {
    "command": "dotnet",
    "args": "build"
  },
  "format": true,
  "lint": true,
  "cache": "jj",
  "tests": {
    "beforeRun": "dotnet build",
    "projects": [
      {
        "project": "MyProject.Tests",
        "command": "dotnet",
        "args": "run --project tests/MyProject.Tests --no-build --",
        "filterTemplate": "--filter-class {classes}",
        "classJoin": " ",
        "group": "unit"
      }
    ]
  },
  "coverage": {
    "directory": "./coverage",
    "thresholdsFile": "coverage-thresholds.json"
  },
  "analyzers": {
    "paths": ["analyzers/"]
  },
  "fileCommands": [
    {
      "pattern": "*.fsx",
      "command": "dotnet",
      "args": "fsi --typecheck-only"
    }
  ]
}

Configuration reference

build fields:

tests fields:

tests.projects[] fields:

coverage fields:

analyzers fields:

fileCommands[] fields:

Cache directory

FsHotWatch stores check result caches and the TestPrune database in .fshw/ at the repository root. Add this to your .gitignore:

.fshw/

The cache directory contains:

• cache/ — Cached FCS check results for faster cold starts
• test-impact.db — TestPrune dependency analysis database