hparadiz/yoman
Menu bar calendar for KDE Plasma. Contribute to hparadiz/yoman development by creating an account on GitHub.
0 stars · 0 forks · QML
README
yoman יומן (yomán) = diary, journal, planner, agenda.
A KDE Plasma 6 calendar panel widget. It lives in the panel showing the date, and opens a popup with a month grid and the day's events. It reads your existing calendars - Google Calendar (through KDE Online Accounts) and anything KOrganizer already syncs - and brings upcoming events to your attention with notifications and an optional full-screen alert. yoman is view-only by design: it shows what is coming up and links out to where each event actually lives. It does not create, edit, or delete events - those changes happen at the source (Google Calendar's own apps, KOrganizer, etc.) and show up here on the next refresh. Features
Panel widget with a configurable date/icon and an optional next-event status display. Popup with a month grid, per-day event dots colored per calendar, and day navigation. Scrollable event list with all-day and timed events, recurrence indicators, declined and past-event filtering, and in-progress state. Event details popup: time, location, description, attendees with response status, and Join / Open actions for meeting and event links. Desktop notifications a fixed lookahead before an event starts (via notify-send). Optional full-screen alert for an in-progress event (opt-in in settings). Right-click "Calendars" menu to toggle the visibility of individual calendars. Settings window: General, Appearance, Calendars, Shortcuts, and About tabs. Settings expose only controls that are actually wired. Localized and locale-aware, designed for longer translated strings and RTL layouts.
Calendar sources Both sources are read-only (pull-only).
Google Calendar - added through KDE's own System Settings > Online Accounts, which handles the browser consent and stores credentials in KWallet via libsignon-qt6 / accounts-qt6. yoman never runs its own OAuth flow; the bundled google-token helper silently asks signond for an access token from the already-authorized identity. Every calendar the account can see (primary, shared, holidays, etc.) is discovered automatically. KOrganizer / Akonadi - optional. The bundled korganizer-calendar helper reads events directly out of Akonadi, so whatever KOrganizer is already set up to sync (local .ics, CalDAV, Exchange, and so on, via its own resources) shows up here without yoman needing a client for any of those protocols.
Google in a restricted organization yoman relies entirely on KDE's OAuth2 integration for Google. It asks signond for a token from the account you added in System Settings > Online Accounts and never requests scopes of its own. KDE requests one bundled set of scopes for the whole Google provider, defined in the provider file: /usr/share/accounts/providers/kde/google.provider
That same file also defines the OAuth2 ClientId - the application identity Google sees on the consent screen and in an admin's app-access controls. It is KDE's own registered Google client, shared by every KDE app that uses a Google account; yoman neither has nor registers a client id of its own, so whichever client id is in this file is the one yoman authenticates under. Changing it (or the scopes) here changes it for yoman too. By default that bundle is broad - alongside basic profile/email it currently asks for calendar, tasks, contacts, and YouTube upload: https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/tasks https://www.google.com/m8/feeds/ https://www.googleapis.com/auth/youtube.upload
If your Google Workspace organization restricts third-party app access, consent for that full bundle can be denied outright. When that happens signond never receives a token, so yoman has nothing to read and the account simply produces no calendars. The fix is to narrow the requested scopes to only what yoman needs (calendar access, plus email to label the account) and then re-authorize:
Edit the Scope list in the provider file down to just: https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/calendar
To avoid editing a system file that a package upgrade would overwrite, copy the provider into your user data directory first and edit that copy - libaccounts searches the user directory ahead of the system one, so it takes precedence: mkdir -p ~/.local/share/accounts/providers/kde cp /usr/share/accounts/providers/kde/google.provider \ ~/.local/share/accounts/providers/kde/
Remove the Google account in System Settings > Online Accounts and add it again, so a new OAuth2 token is minted with the reduced scopes. The consent screen should now request only calendar access, which a restricted org is far more likely to allow.
yoman only ever reads, so if your org offers a read-only variant you can substitute https://www.googleapis.com/auth/calendar.readonly - but note that narrowing the shared provider affects every KDE app using this Google account, so anything that writes to the calendar (such as the Akonadi Google resource) would lose that ability. Finally, if your org blocks the integration by application rather than by scope, editing scopes will not help; an admin has to allowlist KDE's OAuth client id (the ClientId shown in the same provider file). Requirements
KDE Plasma 6 with Qt 6 and KDE Frameworks 6 (Kirigami, Plasma). libsignon-qt6 + accounts-qt6 (KAccounts) - standard on a Plasma 6 system; required for the Google source. kpackagetool6 (ships with Plasma) to install the plasmoid. Optional: KDE PIM (KCalendarCore, Akonadi) for the KOrganizer source. If it is not installed, that one build step is skipped automatically and everything else (Google Calendar, the rest of the widget) still works.
Install Build and install for your own user (no sudo needed): ./scripts/install-plasmoid.sh
Add --global to install it system-wide instead. The script compiles the two helper binaries and the small calendarsmenu QML plugin, installs the widget icon into the icon theme, and installs (or upgrades) the plasmoid via kpackagetool6. If a component's dependencies are missing (for example Akonadi), that component is skipped with a message rather than aborting the whole install. A CMake path is also provided for packaging, using ECM and plasma_install_package: cmake -B build -S . && cmake --build build && cmake --install build
Once installed, add it from the panel's "Add Widgets" picker (search for "yoman"), or right-click the panel and add it directly. After an upgrade you may need to restart plasmashell for the running shell to pick up metadata or icon changes. Configuration Settings are stored as a plain INI/GKeyFile at ~/.config/yoman/config.conf ([group] sections, key=value lines). Everything is editable from the in-widget Settings window; the file is written atomically. Calendar sources and account identity are persisted there as source <id> and google account <id> groups. Repository layout plasma/org.yoman.Yoman/ the Plasma plasmoid (the actual product) contents/ui/ QML/Kirigami UI, stores, and shell-out helpers contents/code/ google-token and korganizer-calendar helper sources contents/plugins/ calendarsmenu QML plugin (native submenu + window icon) contents/icons/ widget icon master (org.yoman.Yoman.png) metadata.json plasmoid metadata scripts/ install and packaging scripts docs/ assessment and generation docs screenshots/ README screenshot(s)
Credits yoman is inspired by Calendr, a menu bar calendar for macOS by Paker (pakerwreah). It is meant as a spiritual successor on KDE - one that faithfully recreates Calendr's feature set and feel within the Plasma desktop. Every feature is rebuilt from scratch, natively, in QML/Qt and C for KDE Plasma. License MIT - see LICENSE.