dsh-folderwatch

Wake the agent when the filesystem changes — not when you remember to look.

An agent can already be woken on a clock (scheduled tasks) and on an HTTP request (webhooks). Neither covers the case that actually matters mid-session: something outside the conversation touches a file. A build finishes. A formatter rewrites the tree. A test runner drops a report. A download lands. A colleague pushes into a shared folder. Today the agent finds out only if it happens to look.

dsh-folderwatch arms a directory against the agent that armed it. When the tree changes, the agent receives an exact account of what changed — and can either be woken to act on it or simply find it waiting at its next step.

[folderwatch] 3 changes under /work/shop/reports
watch: reports · 14:02:11
1 created · 1 modified · 1 deleted
  + /work/shop/reports/run-42.json  18KB
  ~ /work/shop/reports/latest.json  18KB
  - /work/shop/reports/run-41.json
(4 events suppressed as this session's own writes)

Read the new report and summarise what failed.

Why it is not just fs.watch and a callback

Three decisions separate a watcher you keep armed from one you uninstall after an afternoon:

1. Snapshots, not raw events

fs.watch reports that something happened, not what. It double-fires on Windows, sometimes reports no filename at all, and silently drops events under load. A watcher built directly on it tells the agent "something changed" — which is not enough to act on.

This plugin takes snapshots and diffs them. Renames, deletions and bursts are classified correctly on every platform, and each change arrives with its size. fs.watch is kept only as a hint to rescan sooner; the periodic rescan is the correctness path.

2. Echo suppression

A watcher on a directory the agent is editing has an obvious failure mode. The agent writes src/app.ts, the watcher fires, the agent is told src/app.ts changed, it reads the file it just wrote. That one settles — but a build, a formatter or a test runner the agent itself started keeps writing, and each write wakes the agent again. The result is a loop that burns tokens and reads as if the workspace were under attack by a stranger.

So tool calls that name a file are recorded in a short-lived ledger, and changes to those paths inside the window are counted as suppressed rather than delivered. The window is deliberately short (echoWindowMs, default 2500ms): a file the agent wrote ten minutes ago changing now is real news.

The suppression is visible rather than silent — every batch reports how many events it filtered, so you can tell "nothing happened" from "the agent did it itself".

3. Delivery is opt-in per watch

mode	call	effect
wake (default)	agent.followup(message)	starts a new turn
queue	agent.inject(message)	waits for the agent's next step

A watcher that can always interrupt is a watcher nobody leaves armed. The quieter option is one argument away, so you can arm a watch for a whole session without handing it the power to interrupt you.

Install

dsh plugin add https://github.com/11111353535/dsh-folderwatch

From a checkout instead of a git host, pass the absolute path:

dsh plugin add /absolute/path/to/dsh-folderwatch

The package declares no dsh-* peer dependency on purpose: it imports only node:* plus @deepseek-ai/dsh-tools, @deepseek-ai/dsh-llm and @deepseek-ai/schemastery, all of which the harness resolves from its own installation. Nothing is bundled that could shadow the host's copy.

To tune it per profile, add a config block to the row the installer inserted in ~/.dsh/profiles/<profile>/cordis.patch.yml:

- insert:
    - id: folderwatch
      name: 'dsh-folderwatch'
      config:
        quietMs: 400
        cooldownMs: 5000
        watches:
          - path: E:/work/reports
            label: reports
            pattern: '**/*.json'
            prompt: Read the new report and summarise what failed.
            mode: wake

key	default	meaning
watches	[]	Watches armed at load time. Arming from a session with the tool is the usual path.
ignore	build/VCS/dependency dirs	Ignore patterns applied to every watch, merged with each watch's own list.
quietMs	400	Quiet period before a batch is delivered.
maxWaitMs	5000	Ceiling on how long changes may wait for quiet, so a never-quiet tree still reports.
cooldownMs	5000	Minimum gap between deliveries for one watch.
pollIntervalMs	1500	How often the tree is rescanned.
maxWatches	16	Maximum number of simultaneously armed watches.
maxEntries	20000	Snapshot entry cap, guarding against a runaway tree.
echoWindowMs	2500	How long a path stays suppressed after this session writes it.
maxEventsPerMessage	60	Events listed in one notification before truncation.

Tools

folderwatch_add

Arm a watch. Returns the arm report, or the reason it could not be armed.

argument	type	meaning
path	string (required)	Directory to watch. Absolute, or relative to the workspace.
label	string	Short name shown in listings and notifications.
prompt	string	Instruction appended to each notification, e.g. re-run the failing test.
pattern	string	Glob selecting which paths are reported, e.g. **/*.log.
ignore	string[]	Extra ignore patterns for this watch. A bare name like tmp matches at any depth.
recursive	boolean	Descend into subdirectories. Defaults to true.
once	boolean	Disarm after the first delivery. Defaults to false.
mode	"wake" | "queue"	Delivery mode. Defaults to wake.
sessionId	string	Session to notify, when it is not the calling one.

dsh-folderwatch · armed "reports"
  root:      /work/shop/reports
  watching:  12 file(s), 3 directories (recursive)
  pattern:   **/*.json
  ignoring:  node_modules, .git
  deliver:   wake the agent (followup)

Changes are reported in batches after the tree goes quiet, and this session's own writes are filtered out.

folderwatch_list

The inventory: what each watch is watching, how often it has fired, and whether anything is pending.

dsh-folderwatch · 2 watches
  reports  running  12 file(s)  2 delivery(ies)  last fired 1m ago
    /work/shop/reports  [**/*.json]
  inbox  stopped  12 file(s)  0 delivery(ies)  never fired
    /work/shop/inbox
    3 change(s) pending delivery

folderwatch_check

Rescan now and report what changed without delivering a message. This is how you answer "has anything happened yet" during a turn instead of waiting to be woken.

dsh-folderwatch · check "reports" · 3 change(s) since the last scan
  + /work/shop/reports/run-42.json  18KB
  ~ /work/shop/reports/latest.json  18KB
  - /work/shop/reports/run-41.json
  (4 further event(s) were this session's own writes)

This was a check: the snapshot advanced and no message was delivered.

folderwatch_fire

Deliver a watch's pending changes immediately instead of waiting for the quiet period. Useful to confirm the delivery path works, or when a batch is known to be complete. When nothing is pending, it says so and sends nothing.

folderwatch_remove

Disarm a watch and release its filesystem handles. Reports what it delivered while armed.

dsh-folderwatch · disarmed "reports"
  root: /work/shop/reports
  delivered 2 batch(es) over 7 event(s) while armed
  filtered 4 event(s) that were this session's own writes

Slash command

/watch                                              # inventory
/watch add ./reports --pattern '**/*.json'          # arm, waking the agent
/watch add ./build --queue                          # arm, waiting for the next step
/watch add ./inbox --once                           # disarm after the first delivery
/watch check reports                                # rescan without delivering
/watch fire reports                                 # deliver now
/watch rm reports                                   # disarm

Behaviour notes

• Batching. Changes are collected until the tree has been quiet for quietMs, or until maxWaitMs has passed, then delivered as one message. A cooldownMs gap prevents a churning tree from producing a stream of messages.
• Recursive on Windows. fs.watch with recursive: true is used where the platform supports it and falls back to a polled walk where it does not. The arm report names which path is in use (watch+poll, poll, …).
• Snapshot caps. A tree larger than maxEntries produces a partial snapshot; the arm report says so rather than silently under-reporting.
• Unreadable directories are counted and named (up to three) in the arm report instead of failing the watch.
• Lifecycle. Watches are registered as effects, so unloading the plugin closes every handle. A watch armed at load time from config still needs a live agent to deliver to; it resolves one by sessionId through the session controller.
• Deletions. A directory disappearing takes its children with it; the diff prunes nested deletions so a removed folder is one event, not one per file.

Development

npm test           # 110 unit tests, no harness needed
npm run test:live  # four real watch scenarios against a temporary directory
npm run setup:deps

lib/ is plain ESM JavaScript with no build step. The unit tests cover the pure modules — glob compilation, snapshot diffing, batching, echo extraction, and every renderer — and the live test covers what fixtures cannot: that a real fs.watch plus poll loop notices an external write, suppresses the session's own write, classifies a deletion, and applies a pattern filter.

dsh-folderwatch live check · win32
  ✓ delivered after an external write: external.txt
  ✓ suppressed this session's own write
  ✓ classified a deletion correctly
  ✓ applied the pattern filter
  4/4 scenarios passed

setup:deps links the host packages lib/ imports (cordis, dsh-tools, dsh-llm, schemastery) into a local node_modules so a bare checkout can run the tests. Set DSH_HOST_NODE_MODULES if the harness is not in a standard location.

License

MIT