FsHotWatch 0.10.0-alpha.3

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 every plugin and reports what each one 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

# The inner loop. 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

# Before you merge: run the full suite and confirm `check` told the truth.
fshw confirm

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

check, confirm, verdict

Three verbs, and the difference between them is the difference between a fast answer and a trustworthy one.

fshw check is the inner loop, and it is not a merge decision. It runs every plugin (build, lint, analyze, test, format-check), but the tests are impact-filtered — it runs the tests a heuristic selector thinks your change can affect. That is a latency optimization, and it is the right trade for the loop you run on every save.

fshw confirm is the merge verb. It runs the same checks with the tests unfiltered, and it refuses to go green unless they actually ran that way — "nothing failed" is not a verdict if the run never produced the evidence (exit 3). Running it beside check is a comparison, and every disagreement is a bug in one of them:

fshw verdict reads the answer back, from a file, without contacting the daemon — see Machine-readable state.

What these verbs do not claim

This matters more than the feature list, so it is stated up front:

• "The full suite" means every test project your .fshw.json knows about — not every test project in your solution. A project that is in the solution but absent from .fshw.json is not run by confirm, and confirm does not claim otherwise.
• Impact selection is still known-unsound. confirm makes the merge verdict unforgeable — a green must be backed by an unfiltered run. It does not make the selector sound: check can still miss tests it should have picked. Those are two different claims and only the first one is fixed.
• A warm cache makes confirm exit 3, not 0. Re-run it on an unchanged tree and the test plugin replays its cached result rather than running; a replay is not evidence, so confirm refuses (exit 3) instead of greening. Clear the cache (rm -rf .fshw/cache) or change a file. It fails safe, but it is a rough edge.

Commands

Add -v for debug logging or -a for agent-friendly, parseable output. Run fshw --help for the full list, and see the CLI README for every verb and flag.

Machine-readable state (for agents and CI)

Don't parse the CLI's output. It is a progress display written for a human and it will change. Every check and confirm publishes its result as a file:

fshw verdict          # stdout: a JSON envelope; exit code: the answer
# 0 green · 1 red · 2 incomplete · 3 unearned scope · 4 STALE · 5 no verdict

.fshw/verdict.json is written atomically at the end of every run — including the ones that fail, time out, or lose the daemon mid-run, which are exactly the moments the human output is least sufficient. It is content-addressed to the tree it verified and the binary that verified it, so a green from a different tree (or from an older, buggier fshw) can never be mistaken for a current one. Reading it opens no socket and starts nothing, so asking cannot perturb the answer.

This — not the progress display — is the surface agents and CI should read. Full schema, exit codes, and the tree-hash recipe: CLI README and ADR-013.

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.