From 4b279bac36f11da7873859cb2527ae30b9c31bbf Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 22 Feb 2026 23:25:51 -0600 Subject: Update README and fix repo references after rename to chime Fix backronym to "CHIME Heralds Imminent Modeline Events" across all files. Update GitHub URLs from chime.el to chime. Add documentation for missing customization variables (notification icon, startup delay, modeline lighter, no-events text, tooltip header format, advance notice, tooltip all-day events). Fix test count (505) and default for chime-day-wide-alert-times. --- README.org | 143 ++++++++++++++++++++++++++++++++++---- chime-debug.el | 2 +- chime-org-contacts.el | 2 +- chime.el | 6 +- convert-org-contacts-birthdays.el | 2 +- 5 files changed, 136 insertions(+), 19 deletions(-) diff --git a/README.org b/README.org index 56c061d..0a15679 100644 --- a/README.org +++ b/README.org @@ -1,5 +1,5 @@ -* *CHIME Heralds Imminent Events* +* *CHIME Heralds Imminent Modeline Events* Customizable org notifications for Emacs with visual alerts, audible chimes, and modeline display. @@ -27,7 +27,7 @@ Customizable org notifications for Emacs with visual alerts, audible chimes, and :CUSTOM_ID: about :END: -CHIME (backronym: *CHIME Heralds Imminent Events*) provides notification support for your org-agenda events. Get visual notifications, a pleasant chime sound, and see your next upcoming event in your modeline. +CHIME (backronym: *CHIME Heralds Imminent Modeline Events*) provides notification support for your org-agenda events. Get visual notifications, a pleasant chime sound, and see your next upcoming event in your modeline. This is an updated and maintained fork of the abandoned [[https://github.com/akhramov/org-wild-notifier.el][org-wild-notifier]] project, renamed to CHIME with bug-fixes and new features. @@ -39,7 +39,8 @@ Note: while I've found this package to be quite reliable, it's still undergoing :END: - *Visual notifications* with customizable alert times -- *Audible chime sound* when notifications are displayed +- *Audible chime sound* when notifications are displayed (bundled WAV or custom file) +- *Customizable notification icon* for desktop notifications - *Interactive modeline display* of next upcoming event with extensive customization: - Enable/disable modeline modifications - Hover tooltip showing all upcoming events grouped by day @@ -52,8 +53,14 @@ Note: while I've found this package to be quite reliable, it's still undergoing - Works with SCHEDULED and DEADLINE and just plain ol' regular timestamps - Supports repeating timestamps (=+1w=, =.+1d=, =++1w=) - Async background checking (runs every minute) -- Configurable notification filtering by keywords and tags -- [[https://github.com/cjennings/chime.el/tree/main/tests][Well-tested]], including with org-gcal +- *All-day event support* (birthdays, holidays, multi-day events) + - Configurable daily notification times for all-day events + - Advance notice (e.g., "Blake's birthday is tomorrow") + - Show/hide all-day events in tooltip +- *org-contacts integration* with birthday conversion and capture template +- Configurable notification filtering by keywords, tags, and custom predicates +- Configurable startup delay for async org-agenda-files initialization +- [[https://github.com/cjennings/chime/tree/main/tests][Well-tested]], including with org-gcal ** Installation :PROPERTIES: @@ -66,14 +73,14 @@ This package is NOT YET available on MELPA. #+BEGIN_SRC elisp (unless (package-installed-p 'chime) - (package-vc-install "https://github.com/cjennings/chime.el")) + (package-vc-install "https://github.com/cjennings/chime")) #+END_SRC *** use-package with :vc (Emacs 29+) #+BEGIN_SRC elisp (use-package chime - :vc (:url "https://github.com/cjennings/chime.el" :rev :newest) + :vc (:url "https://github.com/cjennings/chime" :rev :newest) :after alert :commands (chime-mode chime-check) :bind ("C-c A" . chime-check) @@ -109,7 +116,7 @@ This package is NOT YET available on MELPA. #+BEGIN_SRC elisp ;; Add to load-path -(add-to-list 'load-path "~/path/to/chime.el") +(add-to-list 'load-path "~/path/to/chime") ;; Load and configure (require 'chime) @@ -125,7 +132,7 @@ Minimal configuration: clone the package somewhere, then add #+BEGIN_SRC elisp - (add-to-list 'load-path "/path/to/chime.el/") + (add-to-list 'load-path "/path/to/chime/") (require 'chime) ;; Alert intervals: notify 5 minutes before (medium) and at event time (high) @@ -200,6 +207,33 @@ Control the audible chime that plays when notifications appear: The package includes a pleasant chime sound in GPL-compatible WAV format. You can use your own sound file if preferred. +*** Notification Icon + +Set a custom icon for desktop notifications: + +#+BEGIN_SRC elisp +;; Use a custom notification icon +(setq chime-notification-icon "/path/to/icon.png") + +;; No custom icon (default: nil, uses system default) +(setq chime-notification-icon nil) +#+END_SRC + +*** Startup Delay + +Control how long chime waits before the first event check after enabling =chime-mode=. This allows org-agenda-files and related infrastructure to finish loading: + +#+BEGIN_SRC elisp +;; Default: wait 10 seconds before first check +(setq chime-startup-delay 10) + +;; Faster startup (if you know org is ready) +(setq chime-startup-delay 5) + +;; Increase if you see "found 0 events" messages on startup +(setq chime-startup-delay 20) +#+END_SRC + *** Modeline Display Display your next upcoming event in your modeline: @@ -219,6 +253,41 @@ The modeline will display the soonest event within the lookahead window, formatt - Default: =⏰ Meeting with Team at 02:30 PM (in 15 minutes)= - Updates automatically every minute +**** Minor Mode Lighter + +The lighter shown in the modeline when =chime-mode= is active: + +#+BEGIN_SRC elisp +;; Default lighter (bell emoji) +(setq chime-modeline-lighter " 🔔") + +;; Text-based lighter +(setq chime-modeline-lighter " Chime") + +;; Minimal +(setq chime-modeline-lighter " C") +#+END_SRC + +**** No-Events Text + +Control what appears in the modeline when no events are within the lookahead window: + +#+BEGIN_SRC elisp +;; Default: alarm icon +(setq chime-modeline-no-events-text " ⏰") + +;; Muted bell +(setq chime-modeline-no-events-text " 🔕") + +;; Show nothing (clean modeline) +(setq chime-modeline-no-events-text nil) + +;; Custom text +(setq chime-modeline-no-events-text " No events") +#+END_SRC + +This only applies when events exist beyond the lookahead window. If there are no events at all, the modeline is always empty. + **** Interactive Modeline Features The modeline text is interactive - you can click it and hover for more information: @@ -252,6 +321,21 @@ The tooltip displays up to 5 events by default. Configure the maximum with: (setq chime-modeline-tooltip-max-events nil) #+END_SRC +Customize the tooltip header format: + +#+BEGIN_SRC elisp +;; Default: "Upcoming Events as of Tue Nov 04 2025 @ 08:25 PM" +(setq chime-tooltip-header-format "Upcoming Events as of %a %b %d %Y @ %I:%M %p") + +;; 24-hour time +(setq chime-tooltip-header-format "Upcoming Events as of %a %b %d %Y @ %H:%M") + +;; Minimal header +(setq chime-tooltip-header-format "Events — %a %b %d") +#+END_SRC + +Uses =format-time-string= codes (=%a= weekday, =%b= month, =%d= day, =%Y= year, =%I= 12-hour, =%H= 24-hour, =%M= minutes, =%p= AM/PM). + ***** Tooltip Lookahead Window The tooltip can show events beyond the modeline lookahead window. By default, it shows events up to 1 year (8760 hours) in the future, while the modeline only shows events within the next hour: @@ -517,7 +601,7 @@ SCHEDULED: <2025-10-30 Thu 10:00> **Notifications:** - All-day events can trigger notifications at configured times -- By default, =chime-day-wide-alert-times= is =nil= (notifications disabled) +- By default, =chime-day-wide-alert-times= is ='("08:00")= (morning notification) - When set, chime will notify you of all-day events happening *today* at those times **** Configuring All-Day Event Notifications @@ -531,7 +615,7 @@ To receive notifications for all-day events (like birthdays): ;; Multiple notification times (setq chime-day-wide-alert-times '("08:00" "17:00")) ; Morning and evening -;; Disable all-day event notifications (default) +;; Disable all-day event notifications (setq chime-day-wide-alert-times nil) #+END_SRC @@ -564,6 +648,39 @@ Control whether overdue TODO items and past events appear alongside all-day even Most users want the default (=t=) to catch overdue items. Disable it if you only want to see today's events and don't want past birthdays/holidays cluttering notifications. +**** Advance Notice for All-Day Events + +Get notified about all-day events before they happen — useful for birthdays (buying gifts) or conferences (packing, travel): + +#+BEGIN_SRC elisp +;; Only notify on the day of the event (default) +(setq chime-day-wide-advance-notice nil) + +;; Notify 1 day before as well +(setq chime-day-wide-advance-notice 1) +;; → "Blake's birthday is tomorrow" at 08:00 the day before +;; → "Blake's birthday is today" at 08:00 on the day + +;; Notify 2 days before +(setq chime-day-wide-advance-notice 2) +#+END_SRC + +Note: This only affects notifications, not tooltip or modeline display. + +**** Showing All-Day Events in Tooltip + +Control whether all-day events (birthdays, holidays, etc.) appear in the modeline tooltip: + +#+BEGIN_SRC elisp +;; Show all-day events in tooltip (default: t) +(setq chime-tooltip-show-all-day-events t) + +;; Hide all-day events from tooltip +(setq chime-tooltip-show-all-day-events nil) +#+END_SRC + +All-day events are never shown in the modeline itself (only timed events appear there). This setting controls only the tooltip display. Notifications are unaffected. + ***** Understanding the Interplay with Alert Times The relationship between =chime-day-wide-alert-times= and =chime-show-any-overdue-with-day-wide-alerts= can be confusing: @@ -811,7 +928,7 @@ For Monday-Friday events, you can either: #+BEGIN_SRC elisp (use-package chime - :vc (:url "https://github.com/cjennings/chime.el" :rev :newest) + :vc (:url "https://github.com/cjennings/chime" :rev :newest) :after alert :commands (chime-mode chime-check) :config @@ -1028,7 +1145,7 @@ emacs & # This creates a SECOND chime instance! :CUSTOM_ID: testing :END: -Chime includes a comprehensive test suite with 339 tests covering all functionality. For detailed information about running tests, test architecture, and development workflows, see [[file:TESTING.org][TESTING.org]]. +Chime includes a comprehensive test suite with 505 tests covering all functionality. For detailed information about running tests, test architecture, and development workflows, see [[file:TESTING.org][TESTING.org]]. Quick start: #+BEGIN_SRC bash diff --git a/chime-debug.el b/chime-debug.el index e9390da..0077585 100644 --- a/chime-debug.el +++ b/chime-debug.el @@ -4,7 +4,7 @@ ;; Author: Craig Jennings ;; Keywords: notification alert org org-agenda debug -;; URL: https://github.com/cjennings/chime.el +;; URL: https://github.com/cjennings/chime ;; This program is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by diff --git a/chime-org-contacts.el b/chime-org-contacts.el index 4be9889..33d6010 100644 --- a/chime-org-contacts.el +++ b/chime-org-contacts.el @@ -6,7 +6,7 @@ ;; Version: 1.0.0 ;; Package-Requires: ((emacs "27.1") (org "9.0")) ;; Keywords: calendar, org-mode, contacts -;; URL: https://github.com/cjennings/chime.el +;; URL: https://github.com/cjennings/chime ;; This program is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by diff --git a/chime.el b/chime.el index 06669e1..a96a1db 100644 --- a/chime.el +++ b/chime.el @@ -1,4 +1,4 @@ -;;; chime.el --- CHIME Heralds Imminent Events -*- lexical-binding: t -*- +;;; chime.el --- CHIME Heralds Imminent Modeline Events -*- lexical-binding: t -*- ;; Copyright (C) 2017 Artem Khramov ;; Copyright (C) 2024-2026 Craig Jennings @@ -9,7 +9,7 @@ ;; Version: 0.6.0 ;; Package-Requires: ((alert "1.2") (async "1.9.3") (dash "2.18.0") (emacs "26.1")) ;; Keywords: notification alert org org-agenda agenda calendar chime sound -;; URL: https://github.com/cjennings/chime.el +;; URL: https://github.com/cjennings/chime ;; This program is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by @@ -26,7 +26,7 @@ ;;; Commentary: -;; CHIME (CHIME Heralds Imminent Events) - Customizable org-agenda notifications +;; CHIME (CHIME Heralds Imminent Modeline Events) - Customizable org-agenda notifications ;; ;; This package provides visual and audible notifications for upcoming org-agenda ;; events with modeline display of the next upcoming event. diff --git a/convert-org-contacts-birthdays.el b/convert-org-contacts-birthdays.el index 21e4019..eea79a8 100644 --- a/convert-org-contacts-birthdays.el +++ b/convert-org-contacts-birthdays.el @@ -6,7 +6,7 @@ ;; Version: 1.0.0 ;; Package-Requires: ((emacs "27.1") (org "9.0")) ;; Keywords: calendar, org-mode -;; URL: https://github.com/cjennings/chime.el +;; URL: https://github.com/cjennings/chime ;; This program is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by -- cgit v1.2.3