WatchFolder for AutoHotkey v2: React the Moment a File Lands — Without Polling

Ever written a script that loops every few seconds checking whether a new file showed up in a folder — and then grabbed it before it finished downloading? WatchFolder is a drop-in AutoHotkey v2 library that fixes both problems. It uses the Windows kernel to tell you the instant a file appears, and it waits until that file is fully written before handing it to you.

Point it at an inbox, a Downloads folder, or a scanner’s output directory and respond in real time. No timers, no half-written files, no wasted CPU.

Why Not Just Poll the Folder?

Polling with a Loop Files on a timer has two nasty habits:

• It burns CPU checking a folder that’s empty 99% of the time.
• It grabs files mid-write. A browser pre-allocates a download at its final size, and encoders like ffmpeg close-and-reopen the file repeatedly — so “the size stopped changing” is a lie, and your script processes a corrupt, half-finished file.

WatchFolder solves both: kernel-level change events (ReadDirectoryChangesW) mean no polling, and an async readiness gate holds every file until its writer has let go.

Watch a Folder in 6 Lines

Create the engine, set a callback, call Start(). That’s the whole pattern:

#Requires AutoHotkey v2.0.2+
#Include lib\WatchFolder.ahk
#Include lib\FolderWatch.ahk
Persistent()
Watcher := FolderWatch(A_Desktop "\Inbox", { Extensions: ["txt", "log"] })
Watcher.OnReady := NewFile
Watcher.Start()
NewFile(Path) {
    MsgBox("Ready: " Path)
}

Drop a .txt into the folder and NewFile fires once the file is fully written. Three clean callbacks cover everything: OnReady, OnRemoved, and OnError.

What You Get

• No polling — kernel change events, not a CPU-wasting timer.
• Never a half-written file — the readiness gate waits for the writer to release the file (with an optional quiet-time settle for ffmpeg & browsers).
• Built-in extension filtering — say ["mp4","csv"] and hear only about those.
• Survives bursts — catch-up-on-start, a periodic reconciliation sweep, and buffer-overflow recovery mean files are never silently missed.
• Optional CLI pipelines — map an extension to a command and let the included dispatchers run it, with real exit codes, retries, and dead-lettering.
• Four worked examples — a graduated tutorial from a one-callback watcher up to a full move-and-track processing pipeline (plus a NotifyV2 toast demo).

Turn New Files Into a Processing Pipeline

Want each new file to trigger a command? The included TrackedDispatcher runs a CLI per file, captures the real exit code without blocking, retries failures with backoff, and dead-letters anything that keeps failing:

fw := FolderWatch(dir, { Extensions: ["csv"] })
t  := TrackedDispatcher(fw, { MaxRetries: 2
    , BackoffMs: [1000, 5000], DeadLetterDir: deadDir })
t.AddRule("csv", 'python process.py "{path}"')
t.OnExit := (Code, Path) => ToolTip(Code = 0 ? "ok" : "failed")
fw.Start()

Get WatchFolder

The full library — all four files, four worked examples, and a 17-page developer guide — for just $4.99.

✅ No license activation required — download it, drop it into your project, and go. No keys, no phone-home, no hassle.

Current price: $4.99  •  Requires AutoHotkey v2.0.2+

Stop Polling. Start Reacting.

Whether you’re building an automated ingest folder, a watch-and-transcode pipeline, or just want to know the second a file shows up, WatchFolder gives you a clean, kernel-backed foundation to build on — in a handful of lines. Brought to you by the-Automator.com.