If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/notify-rs/notify shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 4d ago
• 7 active contributors
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live notify-rs/notify repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/notify-rs/notify.

What it runs against: a local clone of notify-rs/notify — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in notify-rs/notify | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of notify-rs/notify. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/notify-rs/notify.git
#   cd notify
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of notify-rs/notify and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "notify-rs/notify(\\.git)?\\b" \\
  && ok "origin remote is notify-rs/notify" \\
  || miss "origin remote is not notify-rs/notify (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/notify-rs/notify"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Notify is a Rust library that provides cross-platform filesystem event monitoring through a unified API, wrapping native implementations like inotify (Linux), FSEvents/kqueue (macOS), ReadDirectoryChangesW (Windows), and poll-based fallbacks. It abstracts away platform differences so developers can watch file and directory changes with one codebase—applications like rust-analyzer, deno, and cargo-watch rely on it for hot-reloading and file synchronization. Five-package workspace monorepo: notify/ is the core cross-platform watcher engine; notify-types/ defines event types; notify-debouncer-mini/ and notify-debouncer-full/ add event deduplication layers; file-id/ provides file identity tracking. Platform implementations live in conditional compilation blocks within notify/. Examples in examples/ demonstrate usage patterns (raw, debounced, async).

Rust developers building CLI tools, build systems, development servers, and IDEs that need to react to filesystem changes in real-time. This includes maintainers of tools like cargo-watch, watchexec, and mdBook who require robust, low-latency file monitoring across Linux, macOS, Windows, and BSD variants.

Production-ready and actively maintained. The project is at v9.0.0 (RC4) with a structured CI/CD pipeline (.github/workflows/ci.yml), comprehensive test coverage across 5 workspace packages, established MSRV policy (1.88), and is used by major projects (alacritty, deno, rust-analyzer). Regular releases and CHANGELOG maintenance indicate ongoing stewardship.

Standard open source risks apply.

Major version 9 is in release-candidate phase (v9.0.0-rc.4 in workspace). Upgrade path documentation (docs/UPGRADING_V8_TO_V9.md) suggests significant API changes. The project maintains issue templates for bugs, features, and docs, and excludes examples/hot_reload_tide due to a noted rustsec dependency issue (#501), indicating active issue triage.

git clone https://github.com/notify-rs/notify.git
cd notify
cargo build --workspace
cargo test --all
cargo run --example monitor_raw

Daily commands:

# Run a simple filesystem monitor
cargo run --example monitor_raw -- /path/to/watch

# Run debounced example (groups events)
cargo run --example debouncer_mini -- /path/to/watch

# Run tests
cargo test --workspace

# Check all workspaces build
cargo build --all

• notify/src/lib.rs: Core public API and platform dispatch logic; defines the Watcher trait and platform-specific implementations behind cfg gates
• notify-types/src/lib.rs: Event types (EventKind, Event, ModifyKind) shared across all packages; breaking changes here require major version bump
• notify-debouncer-mini/src/lib.rs: Lightweight event aggregation layer; shows common pattern for batching duplicate filesystem events
• file-id/src/lib.rs: Cross-platform file identity tracking using inode/file handles; critical for distinguishing file moves from create+delete
• Cargo.toml: Workspace configuration defining all 5 packages, shared dependencies, MSRV policy, and feature flags for OS-specific code
• .github/workflows/ci.yml: CI pipeline; defines test matrix across platforms, clippy/deny checks, and release gates
• docs/UPGRADING_V8_TO_V9.md: Documents breaking API changes in current major version; required reading for understanding design evolution

Platform-specific changes: Edit notify/src/lib.rs (main API) and conditional compilation blocks for your OS (#[cfg(target_os = "...")]). Event types: Modify notify-types/src/lib.rs. Debouncing logic: Edit notify-debouncer-mini/src/lib.rs or notify-debouncer-full/src/lib.rs. New examples: Add .rs file to examples/ and reference in examples/Cargo.toml. File identity: Extend file-id/src/lib.rs. Always add tests alongside changes and run cargo clippy (config in clippy.toml).

Feature selection matters: inotify watcher is default on Linux, but FSEvents vs kqueue behavior differs on macOS (controlled by optional features). MSRV is strict: Cargo.toml enforces 1.88; upgrading deps can force MSRV bumps (documented in release notes). File identity edge cases: File moves are synthesized from create+delete events on some platforms; file-id's xxHash3 collision odds are non-zero on hash mismatches. Debouncer jitter: debouncer-mini uses flume::bounded() channels; overflow behavior differs from debouncer-full. Platform-specific event semantics: Metadata changes emit DirtyDist differently (inotify vs FSEvents); tests via insta snapshots capture these.

• inotify (Linux) — Core filesystem monitoring backend on Linux; understanding inotify masks, watches, and IN_CLOSE_WRITE semantics explains event boundaries in notify
• FSEvents (macOS) — Native macOS monitoring API with directory-level granularity; explains why notify coalesces events on macOS and infers file vs directory changes
• kqueue (BSD/macOS) — Alternative BSD-family monitoring mechanism; notify supports it as an optional macOS backend for lower-level control vs FSEvents
• ReadDirectoryChangesW (Windows) — Windows native API for directory monitoring; explains why Windows watcher is less fine-grained than Linux and requires completion ports for async behavior
• Event debouncing / coalescence — Both debouncer packages implement time-window or batch-size based event aggregation; critical for performance when many files change rapidly (e.g., bulk saves, npm install)
• File identity / inode tracking — file-id crate uses device + inode (Unix) or file ID (Windows) to detect renames vs delete+create; essential for build systems that need to follow moved source files
• Conditional compilation / feature gates — notify uses #[cfg(target_os = ...)] and Cargo features to compile only relevant OS-specific code; understanding cargo feature matrices is vital for maintaining multi-platform Rust

• watchexec/watchexec — Heavy user of notify; demonstrates how to build a production CLI tool on top of the watcher API with signal handling and debouncing
• rust-lang/cargo-watch — Canonical example of notify used in a widely-deployed Rust tool; shows integration with subprocess management and live reload workflows
• denoland/deno — Major consumer of notify for file watching during development and testing; code examples of async watcher usage
• notify-rs/notify-rust — Related project in same org but solves a different problem: desktop notifications (balloon popups) instead of filesystem events
• rfsnotify/rfsnotify — Predecessor inspiration (Go fsnotify); Rust's notify was born out of frustration with lack of equivalent—understanding rfsnotify's API choices illuminates notify's design

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for cross-platform watcher behavior in notify/tests/

The repo lacks explicit integration tests comparing watcher behavior across platforms (Linux inotify, macOS FSEvents, Windows ReadDirectoryChangesW). Given that notify is used by production tools like alacritty and cargo-watch, adding platform-specific test cases would catch regressions early. The test_cases/ directory in notify-debouncer-full shows the pattern (hjson-based tests), but the core notify crate has no equivalent.

• [ ] Create notify/tests/integration/ directory structure
• [ ] Add platform-specific test modules: linux_inotify.rs, macos_fsevents.rs, windows_readchanges.rs
• [ ] Test edge cases: rapid file creation/deletion, symlink handling, permission changes per platform
• [ ] Reference existing test patterns in notify-debouncer-full/test_cases/ for consistency
• [ ] Document platform-specific behavior in docs/ if discrepancies are found

Add CI workflow to test MSRV (1.88) compliance across all workspace members

The workspace.package defines rust-version = 1.88, but .github/workflows/ci.yml likely doesn't explicitly test against this MSRV. With 6 workspace members (notify, notify-types, notify-debouncer-mini, notify-debouncer-full, file-id, examples), an MSRV test job would prevent accidental use of newer Rust features and catch breakage for users on older stable versions.

• [ ] Review .github/workflows/ci.yml to confirm no MSRV job exists
• [ ] Add new CI job using rustup with 1.88 toolchain
• [ ] Run 'cargo +1.88 check' and 'cargo +1.88 test' for all workspace members
• [ ] Ensure deny.toml and clippy.toml are compatible with 1.88
• [ ] Document MSRV policy in CONTRIBUTING.md or README.md

Add platform-specific feature documentation in docs/PLATFORM_SUPPORT.md

README.md lists supported platforms but lacks a dedicated guide explaining watcher backend differences (inotify recursion limits on Linux, FSEvents vs kqueue trade-offs on macOS, ReadDirectoryChangesW buffer constraints on Windows). New contributors and users often misunderstand platform-specific limitations. This doc would clarify when to use RecommendedWatcher vs specific backends and explain events that may differ per-platform.

• [ ] Create docs/PLATFORM_SUPPORT.md with sections for Linux, macOS, Windows
• [ ] Document backend choice logic for RecommendedWatcher on each platform (see src/ backend selection)
• [ ] List known limitations: inotify recursion, FSEvents latency, Windows network drives
• [ ] Add event reliability matrix (which EventKind values are guaranteed per-platform)
• [ ] Link from README.md and add reference in examples/README.md

• Add integration tests for examples/hot_reload_tide/ with the dependency fix from rustsec #501; currently excluded from workspace. This involves updating Cargo.lock and verifying the example still runs end-to-end.
• Write cross-platform documentation examples for file-id collision handling and file move detection semantics in docs/. The current docs mention xxHash3 but don't explain recovery strategies when identity check fails.
• Implement Debug and Clone derives (or manual impls) for platform-internal types in notify/src/ to improve ergonomics for library users who need to inspect/store watcher state during testing.

The notify-rs codebase demonstrates solid security practices with workspace dependency management, security policy documentation, and active vulnerability scanning via deny.toml. The primary concern is an excluded example with a known unresolved vulnerability. Dependencies are generally well-maintained with recent versions. The library's core functionality involves extensive filesystem access, which is intentional but requires user awareness. Overall security posture is good, with recommendations focused on strengthening version constraints and ensuring vulnerability disclosure procedures are complete.

• Medium · Excluded Dependency with Known Vulnerability — Cargo.toml (workspace exclusions), examples/hot_reload_tide/. The example 'hot_reload_tide' is explicitly excluded from the workspace due to an unresolved rustsec issue #501. This indicates a known security vulnerability in one of its transitive dependencies that has not been patched. Fix: Monitor rustsec issue #501 for resolution. Once resolved, either update dependencies or re-include the example. In the meantime, ensure this example is not used in production and document the security limitation.
• Medium · Permissive Dependency Version Ranges — Cargo.toml workspace dependencies. Several dependencies use minimum version specifications without upper bounds (e.g., libc = '0.2.4', windows-sys = '0.61.0'), which could introduce breaking changes or security issues from minor/patch updates. The workspace dependency resolution might not catch all transitive vulnerability updates immediately. Fix: Consider using more restrictive version constraints (e.g., '0.2.*' instead of '0.2.4') or implementing a deny.toml advisory vulnerability scanner. The project appears to already use deny.toml - ensure it's configured to catch advisory vulnerabilities.
• Low · Extensive File System Access Capabilities — notify library core functionality. This is a cross-platform filesystem notification library with permissions to monitor and potentially access filesystem operations across multiple platforms (Linux, macOS, Windows). While this is the library's intended purpose, it requires careful usage in security-sensitive contexts. Fix: Users should ensure proper permission boundaries when using notify. The library should clearly document file access scope and recommend using with principle of least privilege. Consider adding security guidelines in documentation.
• Low · Missing SECURITY.md Implementation Details — .github/SECURITY.md. While a SECURITY.md file exists (.github/SECURITY.md), the actual content is not provided. This may lack vulnerability disclosure procedures or security contact information. Fix: Verify that SECURITY.md contains: (1) Vulnerability disclosure policy, (2) Security contact email, (3) Timeline for security patches, (4) Any known limitations or security considerations for the library.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.