Calendar Integration

Connect your calendars to GDT and see your schedule alongside your tasks. Ask about meetings, find free time, and plan your day—all through natural conversation.

What You Can Do

• View your schedule: "What's on my calendar today?" shows a visual timeline
• Check availability: "Am I free tomorrow at 2pm?" gives instant answers
• Find focus time: "Find 2 hours for deep work this week" locates open slots
• See conflicts: GDT warns when tasks overlap with meetings
• Combine sources: View Google Calendar, iCloud, and system calendars in one place

Prerequisites

Before connecting, you'll need:

Calendar	Requirements
Google Calendar	OAuth credentials from Google Cloud Console (Client ID + Secret)
iCloud	Apple ID + App-specific password
System Calendar	macOS or Windows with calendar access permissions

First time with Google OAuth?

Create a project in Google Cloud Console, enable the Calendar API, and create OAuth 2.0 credentials. GDT will guide you through the authorization flow.

Connecting Calendars

Google Calendar

1. Run /calendar connect or say "connect my Google calendar"
2. Choose Google Calendar
3. Enter your OAuth Client ID and Secret
4. Complete authorization in your browser
5. GDT stores credentials securely in your system keychain

iCloud Calendar

1. Run /calendar connect
2. Choose iCloud Calendar
3. Enter your Apple ID and app-specific password
4. GDT connects via CalDAV protocol

System Calendar

1. Run /calendar connect
2. Choose System Calendar
3. Grant calendar access when macOS/Windows prompts

Viewing Your Schedule

Ask naturally:

What's on my calendar today?
Show me tomorrow's meetings
What do I have this week?

Timeline Views

GDT presents your schedule visually based on the time range:

Single day — detailed 30-minute slots:

Today: 2026-01-25 Saturday
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
09:00 ██████  Team standup (1h)
10:00 ▓▓▓▓▓▓  Project sync (30m)
10:30 ░░░░░░  (available)
14:00 ░░░░░░  (available)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scheduled: 1.5h | Available: 6.5h

2-4 days — side-by-side comparison:

       1/25 (Sat)                    1/26 (Sun)                    1/27 (Mon)
       ────────────────────────────  ────────────────────────────  ────────────────────────────
09:00  ░░░░░░                        ░░░░░░                        ██████ Team standup
10:00  ██████ Project review         ░░░░░░                        ▓▓▓▓▓▓ Design sync
       Scheduled: 2h                  Scheduled: 0h                 Scheduled: 4h

5-7 days — week overview with occupancy percentages.

Visual Legend

Pattern	Meaning
██████	Busy (meetings, fixed events)
▓▓▓▓▓▓	Busy (alternating for readability)
░░░░░░	Available
······	Breaks, lunch, transitions
⚠️	Conflicts or cross-day events

Checking Availability

Am I free tomorrow at 2pm?
When's my next free slot?
Find 2 hours for deep work this week

GDT considers all connected calendars when answering.

Commands Reference

Command	Description
/calendar connect	Start connection wizard
/calendar list	Show connected calendars
/calendar sync	Force immediate sync
/calendar disconnect	Remove a calendar connection
/calendar today	Show today's schedule
/calendar week	Show this week's schedule
/cal	Shorthand for /calendar

How Events and Tasks Work Together

GDT keeps calendar events and tasks separate—and that's intentional.

Events are scheduled time blocks: meetings, appointments, calls. They have fixed start and end times.

Tasks are work you need to complete: action items, deliverables, to-dos. They're flexible about when you do them.

This separation helps GDT give better answers:

You: What should I work on between meetings today?

GDT: You have 2 hours free from 2-4pm. Based on your tasks:
     - "Review quarterly report" (due tomorrow, ~1h)
     - "Reply to Sarah's email" (quick, ~10min)

     Want me to schedule focus time for the report?

GDT stores events in its calendar cache and tasks in TaskWarrior. This means:

• Your calendar app stays the authority for scheduling
• TaskWarrior handles your GTD workflow
• Neither system gets cluttered with the other's data

Technical details: iCalendar RFC 5545

Events (VEVENT) and tasks (VTODO) are defined as distinct components in RFC 5545. Events have DTSTART/DTEND and block time; tasks have STATUS and PERCENT-COMPLETE for tracking progress. GDT respects this semantic distinction.

Security & Privacy

Your credentials stay on your device:

1. System keychain (preferred): macOS Keychain, Windows Credential Manager, or Linux libsecret
2. Encrypted file (fallback): AES-256-GCM with machine-specific keys

OAuth tokens refresh automatically. If they expire completely, GDT asks you to re-authorize rather than storing long-term passwords.

What GDT accesses:

• Event titles, times, and status (busy/free)
• Calendar names for organization

What GDT doesn't access:

• Event descriptions or notes
• Attendee email addresses
• Meeting links or attachments

Sync Behavior

Setting	Default	Notes
Auto-sync interval	5 minutes	Runs in background
Adaptive range	30s - 10min	Adjusts based on API response time
Manual sync	/calendar sync	Immediate refresh

Sync happens silently without interrupting your workflow. A status indicator shows sync state in the corner.

Troubleshooting

"Authentication failed" when connecting Google Calendar

Your OAuth credentials may be invalid or expired.

1. Verify your Client ID and Secret in Google Cloud Console
2. Check that the Calendar API is enabled for your project
3. Run /calendar disconnect then /calendar connect to reconnect

Calendar shows no events but they exist

The sync may not have completed yet.

1. Run /calendar sync to force an immediate sync
2. Wait a few seconds and ask again
3. If still empty, check that you granted calendar access permissions

iCloud connection fails with "invalid credentials"

App-specific passwords can expire or get revoked.

1. Go to appleid.apple.com → Security → App-Specific Passwords
2. Generate a new password for GDT
3. Run /calendar disconnect then reconnect with the new password

Events from one calendar don't appear

You may have multiple calendars in the same account, and only some are synced.

1. Run /calendar list to see which calendars are connected
2. Some calendar providers only sync the primary calendar by default

FAQ

Can I create calendar events from GDT?

Not yet. GDT currently provides read-only access. This is intentional:

• Prevents accidental event creation or deletion
• Keeps your calendar app as the source of truth
• Avoids sync conflicts

Future versions may add write capabilities with safeguards.

Why do I need to provide OAuth credentials for Google Calendar?

Google requires OAuth for calendar access. GDT doesn't have a centralized server that could handle this for you—everything runs locally on your machine. You create your own OAuth app so credentials stay under your control.

How does GDT handle all-day events?

All-day events appear at the top of your daily view without blocking specific time slots. GDT considers them when suggesting scheduling but won't mark entire days as "busy."

What about recurring events?

GDT expands recurring events into individual instances within your queried date range. Each instance shows its recurrence pattern (e.g., "Daily standup - repeats weekdays").

Next Steps

• GTD Workflow — Learn how GDT handles your to-do list
• Natural Conversation — Tips for talking to GDT effectively
• Privacy & Data — How GDT protects your information