Shift Sleep Planner

Night and rotating shifts push sleep into whatever gaps are left. Can a planner turn published sleep guidance into concrete times for one person's roster, show where each rule comes from, and do it without the schedule ever leaving the phone?

A pure-function planner puts the main sleep in the longest free gap (or, after a night shift, the first gap after a 30-minute wind-down), adds naps before night shifts, tops the day up to the target, and derives a caffeine cutoff and a dim-light window from each main sleep. Every default can be changed in settings.

Shift, unavailable-time and actual-sleep blocks can cross midnight; overlapping blocks are rejected before they are saved. A today/tomorrow timeline and a weekly chart show the plan, and every recommendation carries its source tag.

An optional one-paragraph weekly summary from Claude (claude-haiku-5-5) runs through a Vercel serverless function. It is off by default and asks for consent when switched on. Before every request it shows the exact JSON that will be sent. Calls are limited per device, per IP and per day overall. On the live demo no API key is configured, so the summary there is a fixed example sentence labelled “데모 예시” (demo example); it does not analyse the data sent.

Shift and sleep times are stored only in the browser's IndexedDB on the phone. There is no account and no server-side copy; backup is a JSON file the user exports and imports.

The AI summary receives aggregates only: total sleep minutes and nap counts for the days the user actually logged (numbered 1–7 instead of dates), the deficit over those days, the target and the number of unlogged days. It never receives dates, clock times, notes or plan estimates.

The browser and the server run the same validator. It allows only listed keys and values in range, requires the totals to match the per-day values, and rejects anything that looks like a time or a date. The API key is kept in a server environment variable. If a public deployment has no API key or no rate-limit store, the function does not call the model and returns a fixed summary labelled as a demo example. The live demo runs in this mode.

64 Vitest tests check: shifts that cross midnight; overlap rejection; nap placement and the 30-minute margin; caffeine-cutoff arithmetic; 24-hour totals and deficit accumulation, including the on-screen “surplus does not offset” rule; that the AI payload contains no time, date or note from a sample week; server rate limits and demo mode; and the serverless function's import paths.

The AI summary handler is tested only with a fake model. It has never been run with a real API key, so the quality of a real summary is untested.

Three fictional schedules (day shifts only, a run of night shifts, a mixed rotation) are checked for overlaps and used for every screenshot. On the production deployment, a valid payload gets the labelled example summary and a payload containing a time is rejected with HTTP 400.

For a fictional 22:00–06:00 night shift, the plan is: main sleep 06:30–13:30, a 90-minute nap 20:00–21:30 before the next shift, and a caffeine cutoff at 00:30, which the app flags because it falls in the middle of the shift.

In the fictional night-shift week the logged-days deficit is 3 h 30 min: 30 min on a short night before the night run, then 2 h and 1 h on the first two daytime sleeps after night shifts. A 9-hour day does not cancel any of it.

Writing the rules down exposed a conflict in my own brief: a 20-minute nap that must end 30 minutes before the shift cannot fit a gap of 45–49 minutes. The app keeps the margin, skips the nap and says why.

The first deployment found a bug the local tests had missed: the serverless function failed with ERR_MODULE_NOT_FOUND, because Node's native ES modules need explicit file extensions. A test now walks the function's import graph.

I wrote the brief: which rules to apply and their sources, the privacy constraints, what the AI may receive, and the review changes (logged-days-only deficit, wind-down margin, call caps).

Claude implemented the app, tests and deployment in bounded steps. I reviewed its output and keep responsibility for the claims on this page.

Not medical advice. The app diagnoses nothing; it tells users to seek medical advice if insomnia or severe sleepiness persists.

I have not tested whether using the app improves sleep, alertness or safety. The tests show that the rules are applied as written, not that the rules help.

The rules are simplified readings of the cited guidance. The 24-hour total, the wind-down and wake-up margins and the placement heuristics are my own choices, labelled as such in the app.

Every schedule in the code, tests, demo and screenshots is fictional. No real roster was used.

The live demo's AI summary is a fixed example sentence, not an analysis, and the summary handler has only been tested with a fake model. A real summary could be wrong. The feature is optional, and the app works fully without it.

The source and a README listing every rule, default and app-defined choice are public. All screenshots come from the built-in fictional demo schedules.

Watson et al., Recommended Amount of Sleep for a Healthy Adult (AASM–SRS, 2015) ↗

NIOSH, Training for Nurses on Shift Work and Long Work Hours (Pub. 2015-115) ↗

Drake et al., Caffeine effects on sleep taken 0, 3, or 6 hours before going to bed (2013) ↗