feat: Google Calendar integration via gws CLI

[xfalcox]

Summary

• Adds a GCalendar service that fetches events from Google Calendar using the gws CLI (gws calendar +agenda)
• Displays subtle dot indicators on calendar days that have events
• Shows upcoming events in a dedicated row below the calendar in the dashboard (default off)
• Shows upcoming events in a scrollable sidebar widget below notifications (default on)
• Sends desktop notifications before events start (configurable minutes)
• Caches events to disk (gcalendar.json) for instant display on shell restart
• Fully configurable via services.calendar, dashboard.showUpcoming, and sidebar.showUpcoming in shell.json, calendar disabled by default

Configuration

{
  "services": {
    "calendar": {
      "enabled": true,
      "command": "gws",
      "agendaDays": 30,
      "dashUpcomingHours": 24,
      "sidebarUpcomingHours": 120,
      "reminderMinutes": 10,
      "refreshInterval": 900
    }
  },
  "dashboard": {
    "showUpcoming": false
  },
  "sidebar": {
    "showUpcoming": true
  }
}

Option	Default	Description
services.calendar.enabled	false	Master toggle — requires gws CLI in PATH
services.calendar.command	"gws"	Path or name of the gws binary
services.calendar.agendaDays	30	How many days ahead to fetch events
services.calendar.dashUpcomingHours	24	Hours ahead to show in dashboard upcoming list
services.calendar.sidebarUpcomingHours	120	Hours ahead (5 days) to show in sidebar upcoming list
services.calendar.reminderMinutes	10	Minutes before event to send notification (0 to disable)
services.calendar.refreshInterval	900	Refresh interval in seconds
dashboard.showUpcoming	false	Show upcoming events row in dashboard
sidebar.showUpcoming	true	Show upcoming events widget in sidebar

When dashUpcomingHours or sidebarUpcomingHours exceeds 24, dates are shown as "Today", "Tomorrow", or "Wed, Mar 18" alongside the time.

Screenshots

Calendar dots + upcoming events row

Events are shown in their own row below the calendar, so they don't stretch the DateTime/Resources columns.

[PixelKhaos]

Oh neat, I'll check this out, but at first glance I'm not a fan of adding the upcoming as a new section in the dashboard to make it even taller, maybe if it was a carousel type thing yo navigate to in the calendar container itself.

I had an early draft of a local calendar integration myself and handled it with UI by clicking into a day to add the events. The idea from there was to expose "upcoming event" in the sidebar under notifications instead.

Here's what I had at that time, just never got back to it.

503612029.mp4

[xfalcox]

Oh neat, I'll check this out

Thanks! I saw your work before starting on this too! Really nice!

but at first glance I'm not a fan of adding the upcoming as a new section in the dashboard to make it even taller, maybe if it was a carousel type thing yo navigate to in the calendar container itself.

My idea is to stop missing meetings at work, so I made the upcoming section very dynamic. It doesn't show most of the time, only appears when there is an upcoming meeting with a configurable threshold that defaults to 24h. That way is captures the user attention whenever the section is rendered to make the user aware something is coming soon.

I expanded the upcoming to 10 days to take the screenshot so it would show, but usually it will be a very subtle integration with only the dots

I had an early draft of a local calendar integration myself and handled it with UI by clicking into a day to add the events. The idea from there was to expose "upcoming event" in the sidebar under notifications instead.

This is fire. What was your storage for events?

For me, I have several systems that all feed into my work Google Calendar, so what I really need is just a way to be alerted of what is coming when I'm on my desktop.

[PixelKhaos]

I expanded the upcoming to 10 days to take the screenshot so it would show, but usually it will be a very subtle integration with only the dots

Oh okay, yeah, if it's more of an option thats fine, but I think it could be worth making it into a dynamic module that can also be added to the sidebar, maybe closed and expanded on demand, but there's plenty space there

This is fire. What was your storage for events?

I was just using plain JSON file, first just as a proof of concept, but that does also help with any portability and non-reliance of external APIs, or even just to centralize several APIs into one source for the system, i.e Outlook and Google.

[xfalcox]

I was just using plain JSON file, first just as a proof of concept, but that does also help with any portability and non-reliance of external APIs, or even just to centralize several APIs into one source for the system, i.e Outlook and Google.

Yeah, gws is returning a simple JSON, so we could standardize into a format and then anything can get to with by simply formatting their JSON properly.

[PixelKhaos]

Yeah, gws is returning a simple JSON, so we could standardize into a format and then anything can get to with by simply formatting their JSON properly.

Yeah, a making the calendar service an endpoint aggregator pretty much.
That way it's easy to just add on more external APIs later.

Other than that, I do suggest using the sidebar for upcoming events :)

oh and for context, this was my branch, it's outdated now but should still work?
I just handled the popups and fields so wrong lmao, it is one of my first edits to the shell and all
https://github.com/PixelKhaos/shell/tree/calendar-events

[PixelKhaos]

@xfalcox oh I did actually find that I had the sidebar events example still, but with kinda incomplete layout and styling there too, I was sure I had an expand/collapse on it, but I guess not.
But it would show only when there were events the same day, but I guess that could be something to configure of how far ahead you want it to surface.

[xfalcox]

Added a scrollable container on the sidebar @PixelKhaos

[xfalcox]

@soramanew would you consider this PR? Let me know what you think about it, I can change it to better fit your vision if necessary.

[PixelKhaos]

Missing import QtQuick for Item

[soramanew]

Sorry I've kinda been putting this one off cause it's quite a large pr.

I like the dots for the events, however the event display below makes the dashboard too tall. I'd much rather have a click to show events on that day instead.

We can also maybe integrate a small daily event counter into the clock to the left (e.g. an icon then # events or something like that).

On another note, is GWS cli required for this? Or is there some other way we can authenticate and pull data from Google calendar? And does this work with other calendars, or is it solely for google calendar?

[PixelKhaos]

On another note, is GWS cli required for this? Or is there some other way we can authenticate and pull data from Google calendar? And does this work with other calendars, or is it solely for google calendar?

This particular approach is GWS only, I previously suggested it to instead be built as it's own local solution that can connect with other sources to import, maybe CLI to push changes too.

By the sounds of it, should be a little bit closer overall to what I did, clicking a day to open the events there, able to add new ones and all.

Another feedback from me is some way to dismiss/hide certain events, or filter holidays and limit the number of shown events at a time in the widget, unless scrolling is added instead. Because it can take up more space than needed. Even putting it in a collapsible to open/close it might be something

[Gitkubikon]

Weirdly enough, everyone was implementing this on their own. And now we are coming together. I think this is a sign we need this PR merged :D

recording_20260404_01-50-45.mp4

[xfalcox]

Sorry I've kinda been putting this one off cause it's quite a large pr.

Yeah, it started small but the service to fetch data added quite a bit quickly.

I like the dots for the events, however the event display below makes the dashboard too tall. I'd much rather have a click to show events on that day instead.

That is default disabled now.

We can also maybe integrate a small daily event counter into the clock to the left (e.g. an icon then # events or something like that).

That's lovely!

On another note, is GWS cli required for this? Or is there some other way we can authenticate and pull data from Google calendar? And does this work with other calendars, or is it solely for google calendar?

GWS cli is the easiest way I found to reliably get the data I needed. I guess it could be done via any other API.

Given the easy JSON format, it means we can handle a pattern any source can easily adapt into.

Another feedback from me is some way to dismiss/hide certain events, or filter holidays and limit the number of shown events at a time in the widget, unless scrolling is added instead. Because it can take up more space than needed. Even putting it in a collapsible to open/close it might be something

There is scroll on the sidebar one! The opt-in top one doesn't because it defaults to a shorter horizon. But should be easy to add that.

Weirdly enough, everyone was implementing this on their own. And now we are coming together. I think this is a sign we need this PR merged :D

Very nice @Gitkubikon !! Yeah, I think having reliable Calendar integration is a must, specially for people who use this shell for their day to day work.