FsHotWatch 0.8.0-alpha.31

FsHotWatch

Trying to speed up the F# development feedback loop.

FsHotWatch is a background daemon that watches your source files and aims to keep the F# compiler warm, so saving a file re-checks just what changed and hands the results to your tools (linters, analyzers, test runners) — instead of each tool restarting the compiler from scratch every time.

Status: early alpha, and a lot of it is AI-written. It runs the author's own daily F# work, but behavior and APIs shift between versions, rough edges are expected, and your mileage may vary. The goal is a faster F# loop — it's still finding its shape, so issues and PRs are very welcome.

The problem

F# tools are slow because each one starts its own compiler from zero. A 15-project solution can take ~2 minutes to analyze. Every save restarts your linter, your analyzer, and your test runner — all re-parsing and type-checking the same hundreds of files again.

How it works

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

1. You save a file — FsHotWatch notices.
2. It re-checks just that file using the already-warm compiler — ideally milliseconds rather than minutes.
3. Plugins get the results instantly — your linter, analyzer, and test runner see the new check results without re-parsing.
4. You query the results — fshw check runs everything and reports what each tool found.

Saves are debounced: if 10 files change at once (a formatter sweeping the repo, say), FsHotWatch waits for things to settle and processes them in one batch.

Quick start

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

# Run all checks. This auto-starts the daemon the first time —
# no separate "start" step needed. Verbose by default.
fshw check

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

fshw init writes a starter .fshw.json; see Configuration.

Commands

Add -v for debug logging or -a for agent-friendly, parseable output. Run fshw --help for the full list.

Packages

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

Configuration

Run fshw init to scaffold a .fshw.json in your repo root, or write one by hand. Every field is optional — sensible defaults apply when omitted.

{
  "build": {
    "command": "dotnet",
    "args": "build"
  },
  "format": true,
  "lint": true,
  "cache": "file",
  "tests": {
    "beforeRun": "dotnet build",
    "dependsOn": ["src/MyApp/Database/Migrations/**"],
    "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"
    }
  ],
  "coverage": {
    "configPath": "coverage-ratchet.json",
    "searchDir": "coverage"
  }
}

Reference

For memory/idle-exit, FSEvents latency, and per-task timeout keys, see Memory & tuning.

build fields:

tests fields:

tests.projects[] fields:

analyzers fields:

fileCommands[] fields:

coverage fields:

Cache directory

FsHotWatch keeps its check-result cache and the TestPrune database in .fshw/ at the repository root. Add it to your .gitignore:

.fshw/

What it does and doesn't cache. The on-disk cache stores FCS check results, keyed by file content — so a fresh daemon can replay unchanged files instead of re-checking them. It does not persist the compiler's in-memory warmth: FSharpChecker and its FCS caches are rebuilt from cold on every daemon start, so the first scan after a (re)start still pays that warm-up before the cached results start landing.

Writing plugins

Plugins are declarative update functions over a shared warm compiler: you define how your state reacts to events (file checked, build completed, tests finished), and the framework manages the agent, status, caching, and IPC. See Writing a plugin.

Memory & tuning

The daemon keeps the F# compiler warm, which costs memory. FsHotWatch ships with conservative defaults (aggressive GC, optional idle-exit) so this stays in check — see Memory & tuning if you want to adjust them.