FsHotWatch 0.8.0-alpha.13

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 — fshw 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)
fshw start

# From another terminal, check what's happening
fshw status

# Run all checks; verbose by default (per-subtask progress + last-run recap)
fshw check

# Prefer one line per plugin?
fshw check --compact   # or -q

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
• ctx.StartSubtask(key, label) / ctx.EndSubtask(key) — surface named concurrent work with live per-subtask elapsed in fshw check output
• ctx.Log(msg) — preferred logging path; appends to the activity tail shown under your plugin in check, and also routes to Logging.info
• ctx.CompleteWithSummary(summary) — override the auto-derived summary captured in run history on the next terminal transition (e.g. "built 4 projects")

Status transitions are fully observed: when a plugin moves to Completed or Failed, the host snapshots current subtasks + activity into a bounded run history (per plugin), visible under the check verbose output as started / elapsed / summary on the next run.

Configuration

Create .fshw.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": "file",
  "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"
      }
    ]
  },
  "analyzers": {
    "paths": ["analyzers/"]
  },
  "fileCommands": [
    {
      "pattern": "*.fsx",
      "command": "dotnet",
      "args": "fsi --typecheck-only"
    }
  ]
}

Configuration reference

Per-task timeouts. Any of build[], tests.projects[], and fileCommands[] entries may set their own timeoutSec to override the global default. When a task exceeds its timeout, the daemon kills the child process tree, records the run with outcome timed out (distinct ⏱ glyph in the UI, timed-out token in agent mode), and stays running — the next change retriggers normally.

build fields:

tests fields:

tests.projects[] 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