Windows Reminder

A tiny zero-dependency CLI for showing native Windows tray balloon notifications from local agents and scripts.

Chinese · Quickstart · Usage · Tech Stack

_{Real preview: a local command triggers a Windows tray notification from the repository workflow.}

Why This Exists

Long-running local agents and automation scripts need a simple way to tell you when something needs attention. Windows Reminder gives them a small command-line interface that pops a Windows tray balloon with a title, body, icon type, and display duration.

It is intentionally small: no npm packages, no service process, no network calls, and no application window to keep open.

Quickstart

Prerequisites:

• Windows
• Node.js
• Windows PowerShell 5.1

Run a notification:

node reminder.js "Build complete" "The local task finished successfully." --icon info --time 5

Or call the wrapper script:

.\reminder.cmd "Needs review" "A background agent is waiting for your input." --icon warning --time 10

The command exits with 0 after the tray notification is shown. Argument or notification failures print to stderr and exit with 1.

Usage

node reminder.js "title" "body" [--icon info|warning|error] [--time seconds]
reminder.cmd "title" "body" --icon warning --time 10

Argument	Required	Default	Notes
title	Yes	-	Balloon title, truncated to 60 characters.
body	Yes	-	Balloon message, truncated to 250 characters.
--icon	No	info	One of info, warning, or error.
--time	No	5	Positive integer display duration in seconds.

Agent Call Example

& "C:\Users\Administrator\Desktop\Windows Reminder\reminder.cmd" `
  "Build complete" `
  "Frontend deployment finished." `
  --icon info

Features

• Native Windows tray balloon notifications through System.Windows.Forms.NotifyIcon.
• Small Node.js CLI with predictable argument parsing and exit codes.
• reminder.cmd wrapper for quick use from PowerShell, batch files, and local agent tooling.
• Zero npm dependencies; only Node.js built-in modules and Windows PowerShell are used.
• Safe message limits for notification title and body length.

Tech Stack

Layer	Technology	Purpose
CLI	Node.js built-in modules	Parses arguments and launches the notifier script.
Notification bridge	Windows PowerShell 5.1	Calls .NET Windows Forms APIs for tray balloons.
Shell wrapper	Windows CMD	Lets other tools call reminder.cmd without remembering the Node entry file.
Tests	node:test	Covers argument parsing and CLI behavior.

Exit Codes

Code	Meaning
0	Notification completed successfully.
1	Invalid arguments, missing values, unsupported icon, invalid time, or notification failure.

Development

Run the test suite:

npm test

Note: the CLI integration test shows a real Windows balloon notification for a short duration.

Project Layout

.
|-- reminder.js       # Node.js CLI entry point
|-- reminder.cmd      # Windows command wrapper
|-- notify.ps1        # PowerShell notification bridge
|-- test/             # Node test files
`-- docs/             # Planning and design notes

Safety Notes

• The tool is local-only and does not send notification content over the network.
• PowerShell is launched with -NoProfile, -NonInteractive, and -ExecutionPolicy Bypass for this script invocation.
• Keep the repository path trusted before wiring it into automated agents.

License

No license file is included yet.