Timely

Your terminal calendar. Where time meets the stars.

A unified TUI calendar that brings Google Calendar, Outlook/365, and local events into one terminal interface. Built on rcurses, companion to Heathrow.

Google Calendar in a browser tab. Outlook in another. Work meetings in Teams. Personal events on your phone. Sound familiar?

Timely puts everything in one terminal view with moon phases, planet visibility, weather, and full keyboard control.

Calendar Sources:

• Google Calendar (OAuth2, full read/write/RSVP)
• Microsoft Outlook/365 (device code auth, Graph API)
• ICS file import with RRULE recurring event expansion
• Local events with create/edit/delete

Three-Pane Layout:

• Top: Horizontal month strip with week numbers and event markers
• Middle: Selected week with half-hour time slots and all-day events
• Bottom: Event details with organizer, attendees, description

Astronomy:

• Moon phases with emoji symbols and illumination percentage
• Visible planet indicators (Mercury through Saturn) via ruby-ephemeris
• Sunrise/sunset times
• Solstices, equinoxes, meteor shower peak dates

Weather:

• 7-day forecast from met.no (free, no API key)
• Temperature and conditions shown above each day column

Integration:

• Bidirectional with Heathrow (Z key sends calendar invite to Timely, r replies via Heathrow)
• ICS auto-import from ~/.timely/incoming/
• Desktop notifications via notify-send (libnotify)
• Cross-source deduplication (no duplicates from ICS + Google)

UI:

• Visual 256-color picker for all colors
• Calendar manager (toggle, recolor, remove calendars)
• Preferences popup for colors, work hours, defaults
• Scrollable event detail popup
• Weekend colors (Saturday orange, Sunday red)

gem install timely-calendar

• Ruby >= 2.7
• rcurses gem (>= 5.0)
• sqlite3 gem (>= 1.4)
• Optional: ruby-ephemeris for planet data
• Optional: notify-send for desktop notifications

timely

You need an OAuth2 client (JSON file from Google Cloud Console) and a refresh token (acquired once via the OAuth consent flow). Setup:

1. Create an OAuth2 client in Google Cloud Console

• Go to https://console.cloud.google.com/, create or pick a project
• Enable the Google Calendar API and Gmail API under "APIs & Services"
• Under "OAuth consent screen", configure (User Type: External, add yourself as a test user). Add scopes:
  • https://www.googleapis.com/auth/calendar
  • https://mail.google.com/
• Under "Credentials" → "Create credentials" → "OAuth client ID" → type "Desktop app". Download the JSON.
• Save the downloaded file as <your-email>.json in your safe_dir (default ~/.config/timely/credentials/).

The downloaded JSON has an installed block with client_id and client_secret — that's the structure timely expects.

2. Get a refresh token (one-time)

Run timely and press G, enter your email. Timely will print an authorisation URL, open it in your browser, sign in, grant the requested scopes, and copy the resulting code back to timely. The refresh token is then written as <your-email>.txt alongside the JSON.

3. Filenames in safe_dir recap

~/.config/timely/credentials/
  ├─ you@example.com.json   ← OAuth client JSON from Google Cloud Console
  └─ you@example.com.txt    ← refresh token (one line), created by `G` setup

Both files together are what timely needs to refresh access tokens on every sync. Required scopes: https://www.googleapis.com/auth/calendar and https://mail.google.com/ (the Gmail scope is used for invite reading/RSVPs).

1. Register an app in Azure Portal > App Registrations
2. Add Calendars.ReadWrite and offline_access (delegated) permissions
3. Enable "Allow public client flows" in Authentication
4. Press O in Timely, enter the client ID and tenant ID
5. Follow the device code flow (visit URL, enter code)

Config file: ~/.timely/config.yml

location:
  lat: 59.9139
  lon: 10.7522
timezone_offset: 1
work_hours:
  start: 8
  end: 17
week_starts_on: monday
default_view: month
default_calendar: 1

google:
  safe_dir: ~/.config/timely/credentials
  sync_interval: 300

outlook:
  client_id: ''
  tenant_id: common

notifications:
  enabled: true
  default_alarm: 15

colors:
  selected_bg_a: 235
  selected_bg_b: 234
  alt_bg_a: 233
  alt_bg_b: 0
  current_month_bg: 233
  saturday: 208
  sunday: 167
  today_fg: 232
  today_bg: 246
  slot_selected_bg: 237
  info_bg: 235
  status_bg: 235

Timely is the calendar companion to Heathrow, the unified messaging TUI.

From Heathrow: Press Z on a calendar invite email to open it in Timely. The ICS data is auto-imported and Timely jumps to the event date.

From Timely: Press r on an event to compose a reply via Heathrow.

Auto-import: Drop .ics files in ~/.timely/incoming/ and they're imported on next Timely startup.

Released into the Public Domain (Unlicense).

Geir Isene with Claude Code