Calendar Overlays

Read-Only Calendar Overlays

Daylight displays external calendar events alongside your tasks so you can plan your day with full context. Events from Google Calendar, remote ICS feeds, and local ICS files appear in the calendar view and day detail — but Daylight never writes back to these sources. Read-only is the entire point.

Why Read-Only is Deliberate

Two-way calendar sync introduces problems that conflict with Daylight’s local-first architecture:

1. Data ownership: Writing to external calendars means relying on APIs that require authentication, network access, and third-party trust — the opposite of local-first
2. Sync simplicity: Two-way sync between a local file system and a cloud calendar is a different class of problem than reading a feed. The complexity isn’t worth the tradeoff for a task app.
3. No API dependencies: Read-only means no OAuth tokens to refresh, no rate limits to handle, no API deprecations to chase. The app fetches a URL and parses the result.
4. Offline reliability: Cached events work offline. If Daylight wrote to calendars, offline edits would need conflict resolution against a remote source — a problem Daylight deliberately avoids.

Supported Sources

Google Calendar

Fetch events from a public or shared Google Calendar URL. The calendar must be accessible via its ICS export link — no Google API credentials required.

calendars:
  - name: Work
    type: google
    url: https://calendar.google.com/...
    color: "#4285f4"

Events are fetched at the configured refresh interval and cached locally. If the network is unavailable, the last-fetched events are displayed.

ICS Files

Subscribe to any remote ICS feed — team calendars, public event schedules, or shared calendars from other services.

calendars:
  - name: Personal
    type: ics
    url: https://example.com/calendar.ics
    color: "#34a853"

Standard ICS format is supported. Events are parsed, cached, and displayed alongside your tasks.

Local ICS Files

Point directly to an ICS file on your filesystem — useful for calendars synced via Syncthing or exported from other applications.

calendars:
  - name: Local Events
    type: ics
    path: ~/Sync/calendars/events.ics
    color: "#ea4335"

Caching Behavior

How Caching Works

Each calendar source is cached independently based on its type:

Offline Behavior

When the network is unavailable, cached data ensures the calendar view remains functional:

• Cached events: Displayed normally from the local cache, indistinguishable from live data
• No connection: Remote calendars show the last successfully fetched events without error states cluttering the UI
• Stale data indicator: If cached data is older than the configured refresh interval, a subtle indicator shows the last fetch time

Display Integration

Calendar View

Tasks and calendar events are displayed together on the same calendar grid, distinguished by visual markers:

┌─────────────────────────────────────────┐
│ January 2026                            │
├─────┬─────┬─────┬─────┬─────┬─────┬─────┤
│ Mon │ Tue │ Wed │ Thu │ Fri │ Sat │ Sun │
├─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│ 26  │ 27  │ 28  │ 29  │ 30  │ 31  │  1  │
│     │ ■   │ ■ ● │     │ ●   │     │     │
├─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│  2  │  3  │  4  │  5  │  6  │  7  │  8  │
│ ●   │     │ ■   │     │ ● ■ │     │     │
└─────┴─────┴─────┴─────┴─────┴─────┴─────┘

■ = Task scheduled    ● = Calendar event

Day Detail

Clicking a day shows calendar events and tasks together, providing full context for daily planning:

Wednesday, January 28

CALENDAR EVENTS
  09:00 - 10:00  Team standup (Work)
  14:00 - 15:00  Client call (Work)

TASKS
  □ Review documentation
  □ Submit expense report
  ☑ Morning exercise (completed)

Configuration

Adding a Calendar

Calendar sources are configured through the Settings UI:

1. Go to Settings → Calendars
2. Add calendar URL or path
3. Set display name and color
4. Save and sync

Removing a Calendar

Removing a calendar clears its cached events immediately:

1. Go to Settings → Calendars
2. Select calendar to remove
3. Confirm removal
4. Events cleared from cache

Limitations