Skip to main content

​
Smart Scheduling

Smart Scheduling is an intelligent system that automatically schedules your habits and tasks on your calendar, respecting priorities, deadlines, and your preferences.

​
Key Features

Unified Scheduling

Habits and tasks are scheduled together in a coordinated manner, ensuring they don’t conflict

Priority-Aware

Items are scheduled based on priority, with urgent tasks able to bump lower-priority habits

Deadline Intelligence

Automatically infers priority from deadlines - items due soon get scheduled first

Flexible Duration

Habits can have min/max duration bounds, optimizing time based on slot availability

​
How It Works

​
1. Priority Calculation

Every habit and task has an effective priority that determines scheduling order:
PriorityWeightDeadline Inference
Critical4Overdue or due within 24 hours
High3Due within 24-48 hours
Normal2Due beyond 48 hours
Low1No deadline set
Explicit priorities always take precedence over inferred priorities. If you manually set a task as “Critical”, it stays critical regardless of deadline.

​
2. Scheduling Order

Smart Scheduling processes items in this order:
  1. Habits First - Sorted by priority, then by ideal time preference
  2. Tasks Second - Sorted by priority, then by deadline proximity
  3. Bumping - Urgent (critical) tasks can bump lower-priority habit events
  4. Rescheduling - Bumped habits are rescheduled to the next available slot

​
3. Duration Optimization

For habits with flexible duration (min/max bounds), the system optimizes duration based on slot characteristics: 
Ideal Time Match → Maximum duration (get most value from preferred time)
Preference Match → Preferred duration (morning/afternoon/evening/night)
Constrained Slot → Minimum viable duration (still complete the habit)
No Match → Preferred duration (default behavior)

​
Using Smart Schedule

​
From the Calendar

Click the Smart Schedule button in the calendar toolbar to run scheduling for your workspace:
1

Click Smart Schedule

Find the button in the calendar toolbar with the sparkle icon
2

Wait for Processing

The system analyzes your habits, tasks, and existing events
3

View Results

New calendar events appear automatically, with a toast notification showing the summary

​
Automatic Scheduling

Smart Scheduling runs automatically every hour via a background cron job. This ensures your calendar stays up-to-date as you add new habits and tasks.
The cron job only schedules items with auto_schedule enabled. You can enable/disable auto-scheduling per habit or task.

​
Configuration Options

​
Window Days

Controls how far into the future to schedule events (default: 30 days, max: 90 days).

​
Force Reschedule

When enabled, existing scheduled events are deleted and recreated. Use this to completely refresh your schedule.
Force reschedule will delete all auto-generated calendar events and create new ones. Manual events are not affected.

​
Best Practices

While the system infers priority from deadlines, setting explicit priorities ensures your most important work is scheduled first.
Set min/max duration bounds instead of fixed durations. This allows the system to optimize scheduling - using more time in ideal slots and less in constrained ones.
Specify your preferred time (e.g., “07:00” for morning meditation). The system will prioritize these slots and allocate maximum duration when they’re available.
The system uses deadlines to infer priority. Keep your task deadlines accurate for optimal scheduling.

​
API Reference

Smart Scheduling is available via the REST API: 
# Trigger scheduling for a workspace
POST /api/v1/workspaces/{wsId}/calendar/schedule
Content-Type: application/json

{
  "windowDays": 30,
  "forceReschedule": false
}
See API Reference for full details.