Housekeeper Hours Tracker

Raycast Script Commands to track housekeeper hours and calculate monthly pay. Runs entirely locally on macOS, no internet needed.

Built because I got tired of counting hours manually at month-end.

Features

• Clock in / out via Raycast
• Monthly pay calculation with rate scheduling
• Lisbon timezone handling (DST-aware)
• Manual entry for forgotten days
• Archive paid months with history
• CSV export
• All data stored locally, atomic writes

Commands

Command	Args	What it does
Housekeeper In	—	Start a session
Housekeeper Out	—	End session, show session + month totals
Housekeeper Status	—	Current state, today, month, 6mo paid avg
Housekeeper Add Today	HH:MM HH:MM	Add today's session manually
Housekeeper Delete Last	—	Remove the most recent session
Housekeeper Pay	—	Archive oldest unpaid month
Housekeeper Set Rate	rate [YYYY-MM-DD]	Schedule a rate change
Housekeeper Export	—	Export sessions + paid months as CSV

Setup

git clone <repo-url> ~/Documents/raycast-scripts/housekeeper
cd ~/Documents/raycast-scripts/housekeeper
chmod +x *.js

Then in Raycast: Settings → Extensions → Add Script Directory → select the folder.

Requires Node.js.

Data

Stored at ~/Documents/housekeeper-tracker.json. All timestamps UTC in storage, displayed as Lisbon time.

Architecture

housekeeper-lib.js is the shared module with all business logic:

• Lisbon timezone conversions (DST-aware)
• Rate scheduling with effective dates
• Atomic file writes (.tmp + rename)
• Legacy file migration

Each command file is thin — parses args, calls lib, prints result.

Why this exists

This is overkill. A spreadsheet would work fine.

But:

• I wanted to learn Raycast Script Commands
• I wanted to practice Cursor agent mode workflows
• Manual hour counting at month-end was annoying enough to fix

Built in an afternoon with Claude + Cursor.