DEV Community: s t

Half-written files and fs.watch on Windows: what I measured, and why rename fixes it

s t — Wed, 21 Oct 2026 15:57:18 +0000

A lot of small desktop tools talk to other programs through a drop folder: the writer puts a JSON file in a directory, and the app watches the directory with fs.watch. It is simple and needs no ports or sockets. It also has a trap: the watcher can see the file before the writer has finished writing it.

I wanted to know how real that trap is on Windows, so I measured it instead of guessing. Everything below was run on Windows 11 with Node 24. I did not benchmark speed, only which events arrive and what a reader can see.

What fs.watch reports for a plain write

In a single process I wrote a 200 KB JSON file with fs.writeFileSync straight into the watched folder:

rename  a.json
change  a.json

So one write gives two events: rename (the file appeared) and change (the content was modified). Windows reports a file creation as rename, which surprises people who expect create. If the handler assumes one event per file, it runs twice.

Now the same payload written to b.json.tmp and then moved with fs.renameSync to b.json:

rename  b.json.tmp
change  b.json.tmp
rename  b.json.tmp
rename  b.json

The temp name produces its own events (it appears, is modified, then disappears), and the final name gets exactly one rename. When the consumer later deletes b.json, that arrives as one more rename, now with the file gone. Two lessons: filter by the final extension so .tmp events are ignored, and when you get a rename, check whether the file still exists. A rename event does not tell you whether the file was created or removed.

The torn read

A same-process test can't show a half-written file, because writeFileSync has finished before the watcher callback runs. The realistic case is two processes. I made a child process write a 2 MB JSON file in 50 KB chunks with a few milliseconds between them, and read the file from the watcher callback in the parent. Real event files are tiny, so this exaggerates the window. The point is only to show that the failure exists.

Plain write, straight to e.json:

rename e.json  bytes=50021    parses=false
change e.json  bytes=50021    parses=false
change e.json  bytes=2000023  parses=true

The first event fired after the first chunk, and the reader got 50 KB of invalid JSON. Write to e.json.tmp and rename when finished:

rename e.json  bytes=2000023  parses=true

One event, complete file. On the same volume, rename into place is the step that makes the file appear whole, which is why the pattern works. (I am describing what I observed on NTFS here; cross-volume moves are a copy and lose this property.)

Why a delay is not a fix

A common patch is "wait 150 ms, then read". In the plain-write run above, a reader that waits a fixed time is right whenever the writer finishes inside that time and wrong otherwise. The tiny files a hook writes usually finish in well under a millisecond, so it works nearly always, and "nearly always" is the dangerous kind of working. The bigger problem is what happens next. If the reader treats an unparsable file as garbage and deletes it, the event is lost for good: the writer later finishes the file, but it was already removed, and the follow-up change finds nothing.

The pattern I use now

Writer:

const tmp = path.join(dir, `${id}.json.tmp`);
fs.writeFileSync(tmp, JSON.stringify(event));
fs.renameSync(tmp, path.join(dir, `${id}.json`));

Reader:

fs.watch(dir, (_e, file) => {
  if (!file || !file.endsWith('.json')) return;      // ignores *.tmp
  const full = path.join(dir, file);
  let text;
  try { text = fs.readFileSync(full, 'utf8'); }
  catch (e) { if (e.code === 'ENOENT') return; throw e; } // delete event or already handled
  let event;
  try { event = JSON.parse(text); }
  catch { return; }                                  // leave it; do not delete
  fs.unlinkSync(full);
  handle(event);
});

Three details matter. First, ignore names that don't end in .json. Second, treat ENOENT as normal, because the rename event for your own unlink comes back through the same callback. Third, don't delete a file you could not parse. Quarantine it by renaming it to .bad, or leave it, so a bug in a writer leaves evidence.

Also scan the folder once at startup. Events that arrived while the app was closed produce no watcher events at all.

What this does not cover

Rename makes the file appear whole, but it does not make the event unique. Two writers choosing the same name will overwrite each other, so put a timestamp and a random suffix in the name. It also does nothing about a writer that crashes before the rename: you will be left with stale .tmp files, which are worth cleaning up on startup.

My measurements come from one machine, one Node version and one filesystem. A network drive, antivirus filters or a different Windows build may behave differently, so run your own test before relying on any of this.

If you are building a small Windows tool that listens to hooks from other programs, the one rule that held up for me: write elsewhere, rename into place, and never delete what you cannot read.

Context: I hit this in a tray app I sell, CatCode. I'm the author. The details above apply to any Node watcher, with or without that app.

How a desktop pet finds out your AI agent has finished a task

s t — Sun, 18 Oct 2026 22:11:31 +0000

CatCode is a pixel pet that lives on the Windows desktop and reacts when a coding agent finishes a task. This is a walkthrough of how that detection works, taken from the app's code (an Electron app). It is simpler than you might expect, and support differs by agent, so I will be specific about what is and is not covered.

No log scraping, no process polling

CatCode does not tail agent logs, inspect processes or read any agent's internal files. I checked: there is no such code. The whole mechanism is a drop folder:

~/.catcode/events/

Anything that can write a small JSON file there can tell the pet a task is done:

{ "source": "Codex", "task": "update the UI", "message": "finished the check" }

That is the entire protocol: source, task and message. Missing values fall back to defaults.

The watcher

The main process consumes those files with fs.watch. Trimmed from main.js:

function consumeEvent(file) {
  const full = path.join(EVENTS_DIR, file), data = loadJSON(full, null);
  try { fs.unlinkSync(full); } catch {}
  if (!data) return;
  // ...append to a per-day log (only the last 3 days are kept)
  celebrate(`Task complete\n${src} ${msg}`);
}
function watchEvents() {
  for (const f of fs.readdirSync(EVENTS_DIR)) if (f.endsWith('.json')) consumeEvent(f);
  fs.watch(EVENTS_DIR, (_e, file) => { if (file && file.endsWith('.json'))
    setTimeout(() => { if (fs.existsSync(path.join(EVENTS_DIR, file))) consumeEvent(file); }, 150); });
}

Details that come straight from this code:

Events that piled up while the app was closed are consumed on startup.
There is a 150 ms delay before reading, so a half-written file is less likely to be read. It is a mitigation, not a guarantee: the writer uses a plain writeFileSync, and a file that fails to parse is deleted anyway.
Each event file is deleted after it is handled. The app keeps a short in-memory list of recent tasks and a three-day per-agent log for a small "agent report" window.

Claude Code: a real hook

For Claude Code the trigger is its Stop hook. The app has a tray item that writes the hook into ~/.claude/settings.json for you. The resulting entry has this shape (the path to the script is yours to set):

{
  "hooks": {
    "Stop": [
      { "hooks": [
        { "type": "command",
          "command": "node C:\\catcode\\tools\\emit-event.js \"Claude Code\" \"\" \"finished the task\"" }
      ] }
    ]
  }
}

emit-event.js is about 30 lines: it creates the folder if needed and writes {source, task, message} as a timestamped .json file. It also accepts JSON on stdin and uses session_id as the task, if you call it without arguments.

Two honest caveats. First, Stop fires when Claude Code finishes responding, so "task finished" really means "the agent stopped and handed control back". Second, the hook command starts with node, so Node.js needs to be on your PATH.

Codex and Cursor: partial, and manual

This is the part to read carefully. The code has no Codex-specific or Cursor-specific integration. No config file for either is written, and nothing watches either tool. The names appear in the README, in the description, and in the tray's "test" button, which just plays a canned message.

What exists is the generic path: if your tool has a "run a command when finished" mechanism, call the same script with a different source:

node tools/emit-event.js "Codex" "update the UI" "finished the check"

If it has no such hook, you can run that line by hand. The pet reacts identically. So: Claude Code has a tray item that writes the hook for you (or you add it by hand, as above), Codex and Cursor work only if you wire a completion command yourself, and I can't tell you from this code whether either tool offers a suitable hook.

What the pet does about it

celebrate() sends the happy state to the renderer, shows a speech bubble for 6 seconds, then restores whatever state the pet was in before.

There is no sprite sheet. The pet is drawn procedurally: Sprite.makeRenderer(28) creates a 28x28 offscreen canvas, and primitives such as pdisc, ptri and pline plot pixels, which are then scaled up (110, 140 or 180 px depending on the size setting). A pose() function maps the state to parameters. For happy, the code makes the pet bounce, smile, stick out its tongue and wag its tail faster, while the renderer spawns sparks and hearts.

The full state list is: idle, working, waiting, sleeping, happy, play, run, pull. Note that working (the laptop pose) is set by the Pomodoro focus timer or by hand from the tray, not by agent activity. The pet never knows a task is in progress, only that one ended.

Skins are small JSON files rather than images:

{ "id": "ginger-cat", "species": "cat", "pattern": "tabby",
  "palette": { "body": "#f2954e", "shade": "#c26a2c", "belly": "#fbe0c2",
               "stripe": "#b8531f", "eye": "#4fae5a", "nose": "#d98c9a", "inner": "#f0a9b3" } }

Species, pattern (solid, tabby, patch), optional accessory and a palette drive the same drawing code, so a new colour scheme needs no art.

The rest, briefly

It also does the desktop-pet things: eyes and head follow the cursor, Pomodoro focus and break timers, water and stretch reminders, user reminders, and skin import. Memes and images from the internet are off by default and need to be enabled in the tray. The privacy note lists the services the app contacts directly: ipapi.co and open-meteo.com for weather, plus meme/image services only if you opt in.

Get it

CatCode is a Windows app, and the source is closed (proprietary EULA). It costs $5: CatCode on Gumroad.

The installer is not code-signed, so Windows SmartScreen will show an "unknown publisher" warning on first launch.

Disclosure: I am the author of CatCode.

Telegram's WhatsApp import drops your photos: why it happens and how to fix it

s t — Sun, 18 Oct 2026 12:11:24 +0000

You exported a WhatsApp chat, imported it into Telegram, and the text arrived. Every photo, video and voice message turned into a line of text like <attached: IMG-20231104-WA0007.jpg>. The memories are gone and only placeholders remain.

You did nothing wrong, and your export is fine. This is a known Telegram bug that has been open for over a year on Telegram's own tracker (bugs.telegram.org/c/49513), with the same complaint in other bug threads, r/Telegram and Superuser. The text transfers and the media is silently skipped.

This post explains why it happens, and how to import a WhatsApp chat into Telegram with the original dates and the media actually attached: photos, videos, voice messages, round video notes and stickers.

Why the import loses your media

A WhatsApp export is a .zip (or folder) containing a _chat.txt transcript plus the media files. Inside the transcript each media item is only a reference, such as IMG-20231104-WA0007.jpg (file attached). The bytes live in separate image, video and audio files next to the transcript.

Telegram's history import is a multi-step flow. The client is supposed to initialize the import, upload each referenced media file, then finalize so the server stitches the media back onto the right messages. From what I can tell, the problem is in the middle step: the text arrives, but the media never gets uploaded, so the server never receives the files and every attachment stays a text stub. Telegram has not confirmed the exact cause. This is my reading of the API flow, not an official statement.

In one sentence: the media is in your export, but the app's import never gets it to Telegram's servers. Nothing you change on the WhatsApp side fixes that.

The fix: do the media upload step yourself

Telegram exposes an official history-import API with the three calls the app is meant to use:

messages.initHistoryImport starts the import for a chat.
messages.uploadImportedMedia uploads each photo, video, voice note, round video and sticker. This is the step that appears to be missing from the app's import.
messages.startHistoryImport finalizes, so the server attaches every file to the correct message and keeps the original send dates.

tg-import is a small Windows tool I wrote that drives all three calls. It reads a WhatsApp export (.zip or folder) or a Telegram Desktop export (result.json), matches each <attached: ...> reference to its real file, and performs the upload step properly.

What it does:

Transfers photos, videos, voice messages, round video notes and stickers instead of placeholders.
Preserves original dates (see the 1:1 limit below).
Has a dry-run preview (--dry) that shows what will be imported with no login and no upload.
Resumes after a crash instead of re-uploading everything.
Uploads in batches and handles Telegram's flood limits.
Ships as a single Windows .exe, so there is no Python to install.

How to use it

Export your chat. In WhatsApp open the chat, choose Export chat, then Include media. (Or export from Telegram Desktop as result.json.)
Create a free api_id / api_hash at my.telegram.org. These are your own credentials and nothing is sent to a third party.
Preview first. Run tg-import with --dry to see every message and media file it will import.
Run the import against a private 1:1 chat. It does the init, upload and start sequence, batches uploads, and resumes if interrupted.
Check the chat. Your media is there on the original dates, with Telegram's small "Imported" label.

Limits you should know before you try it

Original dates only land correctly in a private 1:1 chat. This is a Telegram server limitation, not a tool bug. Importing into a group or channel will not place messages on their original dates.
Bulk import through the user API is a gray area under Telegram's Terms of Service. tg-import uses your own account and credentials, so it is your account and your own risk. The tool paces requests for flood limits, but it cannot remove the ToS question. If that risk is not acceptable to you, this is not the right tool.
You supply your own api_id and api_hash. They are free from my.telegram.org.

Get it

tg-import costs $9 on Gumroad. Run the --dry preview first: no login, no upload.

Disclosure: I am the author of tg-import.