OpenScheduler

A free, local-first planner that turns your real routine into a schedule you can actually follow.

OpenScheduler asks a handful of adaptive onboarding questions (different questions for a school student vs. a shift worker vs. a freelancer), then generates a day-by-day schedule with a deterministic engine: sleep and fixed commitments are protected first, then routines, then flexible tasks are placed by priority, deadline, energy level, and preferred time of day. Every placement — and every thing that didn't fit — comes with a plain-language explanation.

No account. No server. No tracking. Everything lives in your browser's local storage unless you explicitly export a backup.

Why this exists

Most scheduling apps either require you to hand-place every block yourself, or use an opaque "AI" that can't explain its decisions and can't be trusted with sleep or deadlines. OpenScheduler is deterministic and inspectable: the same inputs always produce the same schedule, and you can read exactly why anything was placed where it was, or why it didn't fit.

Features

• Adaptive onboarding — the questions change based on whether you're a student, a professional, a shift worker, a caregiver, or something else.
• Sleep-first scheduling — sleep is protected before anything else is placed, and no task can displace it.
• Fixed commitments — classes, work hours, appointments, and one-off calendar events always win conflicts, and conflicting commitments are flagged rather than silently dropped.
• Routines — recurring habits with fixed times, preferred windows, or no time preference at all.
• Flexible tasks — priority, deadline, energy level, preferred time of day, and whether a task can be split into multiple sessions.
• Schedule modes — Normal, Busy, Exam/deadline week, Recovery, and Weekend, each adjusting capacity and protected personal time.
• Explanations, always — every scheduled item and every unscheduled item shows the reasoning behind it.
• Week view — a 7-day overview with per-day mode switching.
• Optional AI layer — A built-in AI Planner Coach uses Google Gemini to analyze your daily schedule, suggest optimizations, and answer custom schedule questions. It supports a creator's built-in key or user-pasted custom keys.
• Local-first storage, with export/import — a full JSON backup you can move between devices or restore from.

Getting started

npm install
npm run dev

Then open the printed local URL in your browser.

Configuring AI (Optional)

OpenScheduler operates completely locally by default. To enable the AI Planner Coach:

1. Create a .env file in the root of the project.
2. Add your Gemini API key (get a free key from Google AI Studio):

   VITE_GEMINI_API_KEY=your_key_here

3. Run the development server again. The AI features will be unlocked automatically! Alternatively, users can paste their own API key directly inside the app's settings panel.

Other scripts

npm run build       # type-check and produce a production build in dist/
npm run preview     # preview the production build locally
npm test            # run the engine and storage test suite (vitest)
npm run test:watch  # run tests in watch mode
npm run lint         # oxlint

Project structure

src/
  domain/     Core types (commitments, routines, tasks, preferences, schedule items)
  engine/     The deterministic scheduling engine and its unit tests
  storage/    localStorage persistence, validation, import/export
  onboarding/ The adaptive onboarding wizard
  views/      Landing page, profile picker, day/week views, manage panel, data panel
  styles/     Design tokens and app stylesheet

The engine (src/engine/schedule.ts) is pure and framework-independent — it takes commitments, routines, tasks, and preferences, and returns a DaySchedule. That's what's covered by the unit tests in src/engine/schedule.test.ts, which check sleep protection, commitment conflicts, priority ordering, preferred time-of-day placement, task splitting, transition buffers, and past-deadline handling.

What's intentionally not included yet

In the interest of not shipping fake or half-working features, the following are documented roadmap items rather than implemented:

• .ics calendar export/import — the schedule model is calendar-shaped and this is a natural next step, but it isn't wired up yet.
• Multi-device sync — by design, everything is local-first; sync would need an explicit, opt-in backend and isn't part of this version.

Privacy

All data is stored in your browser's local storage on your device. Nothing is sent to a server. There is no account system and no analytics. Clearing your browser's site data will delete your schedule unless you've exported a backup first (Data tab → Export).

Contributing

Issues and pull requests are welcome. Please run npm test and npm run build before opening a PR — both must pass cleanly. See .github/ISSUE_TEMPLATE for bug report and feature request templates.

License

MIT — see LICENSE.