SchedyX

Local-first timeblocking and scheduling assistant for macOS. SchedyX reads tasks (initially Apple Reminders), finds open time around meetings, and blocks time on your calendar while respecting work hours and constraints. No cloud account required. Optional AI planning can be added later.

Status: Pre-alpha v0.1.0 — core scheduling engine ready for testing.

Why SchedyX

• Local-first: data stays on your Mac.
• Safe by design: only touches events it created (tagged with #autoblock).
• Deterministic core: rules engine decides; AI (optional) only suggests.
• Mock-first: develop and test without touching real calendars.

Key Features

• ✅ CLI commands: init, plan, apply, reconcile, check, clear
• ✅ Smart locking (free → busy at lock window)
• ✅ Task splitting for long tasks (>90m)
• ✅ Diff previews for apply and safe reconciliation
• ✅ Mock adapters for safe development
• ✅ Comprehensive test suite

Screenshots & Demo

Want a live demo? Run the mock workflow below and compare output with the screenshot.

Installation

Prerequisites

• Node.js 18+ (recommended)
• macOS (for real Calendar/Reminders integration)

Install

npm install
npm run build

Quick Start (Mock Mode)

1. Create config at ~/.config/schedyx/config.yaml:

mode: mock
writesEnabled: false
workHours:
  start: "09:00"
  end: "17:00"
lockMinutes: 30
breakMinutes: 10
cooldownMinutes: 5
writeCalendar: "SchedyX Auto"
readCalendar: "SchedyX Auto"
busyCalendars:
  - "Work"
remindersList: "SchedyX Test"
fixtures:
  tasks: "data/fixtures/tasks.json"
  events: "data/fixtures/events.json"

2. Run the planner:

npm start plan

3. Preview apply (no writes):

npm start apply --diff

4. Simulate reconciliation:

npm start reconcile --dry-run

Full walkthrough: docs/QUICKSTART.md

Usage Examples

Initialize real config (interactive)

npm start init

Plan (dry-run)

npm start plan
npm start plan --json

Apply blocks

npm start apply --diff
npm start apply --write

Reconcile after calendar changes

npm start reconcile --dry-run
npm start reconcile

Check recently ended blocks

npm start check
npm start check --write
npm start check --window 10

Manual: run schedyx check after a block ends to confirm completion.

Periodic: wire it into cron or launchd to poll every few minutes. Example (cron, every 5 minutes):

*/5 * * * * /usr/local/bin/node /path/to/schedyx/dist/cli/index.js check --write

Clear auto-blocks and stored state

npm start clear

How It Works (High-Level)

1. Load tasks and calendar events
2. Build available slots (work hours minus meetings + buffers)
3. Schedule tasks into slots (split long tasks as needed)
4. Apply locking (blocks become busy at lockMinutes)
5. Write blocks only when explicitly enabled

State is stored in a local SQLite database at ~/.config/schedyx/state.db.

Troubleshooting

“Config not found”

• Ensure ~/.config/schedyx/config.yaml exists
• Use the exact YAML structure shown above

“Writes are disabled”

• SchedyX is safe-by-default. Use --write or enable writesEnabled: true in config.

“Cannot find module”

• Run npm install and npm run build

AppleScript / Permissions errors

• Grant Calendar/Reminders access in System Settings → Privacy & Security → Automation
• Run npm start init to regenerate config

Documentation

• docs/QUICKSTART.md — Step-by-step getting started guide
• docs/FEATURES.md — Locking, safety, output
• docs/TECH_SPEC.md — Architecture and design
• docs/TESTING.md — Test suite and manual checklist
• docs/ROADMAP.md — Planned features (v0.1, v0.2 self-hosted, v1.0)
• docs/ARCHITECTURE.md — Code structure
• docs/DEVELOPMENT.md — Local dev setup & workflow
• docs/CONTRIBUTING.md — How to contribute
• docs/LIMITATIONS.md — Known constraints & edge cases
• docs/SECURITY.md — Security considerations & reporting
• docs/CHANGELOG.md — Version history

AI-Assisted Development

This project uses AI tools to assist with research, drafting, and code/documentation improvements. All changes are reviewed and tested by a human maintainer before merging.

License

MIT — see LICENSE.