iCalBuddy Color Widget for Übersicht

A beautiful two-column calendar widget for your macOS desktop that displays upcoming events from Apple Calendar using iCalBuddy's colorized output.

Note

The screenshot shows macOS desktop widgets on the left side (not included). This widget only provides the two-column calendar event list.

Features

• Shows upcoming calendar events in a clean, two-column layout
• Color-coded events based on calendar colors
• Auto-updates every 10 minutes (configurable)
• Easy configuration - no need to dig through code
• Customizable positioning, fonts, and appearance

Installation

1. Install Übersicht

If you haven't already, download and install Übersicht, a macOS app that lets you run widgets on your desktop, either from the website or via Homebrew:

brew install ubersicht

2. Install iCalBuddy

iCalBuddy is the command-line tool that fetches your calendar events. You can download it from the home page or use Homebrew:

brew install ical-buddy

3. Install This Widget

Recommended: Download the widget package

1. Download iCalBuddy-Color.widget.zip from the repository
2. Extract it to: ~/Library/Application\ Support/Übersicht/widgets/
3. Übersicht will automatically load it

Alternative: Clone via git (for development)

If you want to contribute or modify the widget:

cd ~/Library/Application\ Support/Übersicht/widgets/
git clone https://forgejo.phoenixtrap.com/mjg/Uebersicht-iCalBuddy-Color.widget.git

Note

This repository is hosted at forgejo.phoenixtrap.com/mjg/Uebersicht-iCalBuddy-Color.widget and mirrored to GitHub per Übersicht widget gallery requirements.

4. Grant Calendar Access

When you first run the widget, macOS will ask for permission to access your calendar data:

1. System Settings will open automatically
2. Enable calendar access for Übersicht
3. The widget will start showing your events

Configuration

All customization is done in the CONFIG section at the top of index.jsx. Just open the file in any text editor and modify the values.

Common Customizations

Change Widget Position

position: {
  top: 40,      // Distance from top of screen (pixels)
  left: 400,    // Distance from left (pixels)
  right: 40,    // Distance from right (pixels)
}

Examples:

• Full width at top: top: 40, left: 40, right: 40
• Right side only: top: 100, left: 1200, right: 40
• Bottom half: top: 600, left: 100, right: 100

Adjust Time Range

calendar: {
  daysToShow: 7,  // Change to 3, 14, 30, etc.
}

Change Font Size

appearance: {
  fontSize: 24,  // Try 18 for smaller, 32 for larger
}

Refresh Frequency

calendar: {
  refreshMinutes: 10,  // Update every 10 minutes (60 = hourly)
}

Column Spacing

appearance: {
  columnGap: 40,  // Space between columns in pixels
}

Advanced Customizations

Custom iCalBuddy Path

If iCalBuddy is installed in a non-standard location:

calendar: {
  icalBuddyPath: '/usr/local/bin/icalBuddy',  // Update this path
}

To find your iCalBuddy path:

which icalBuddy

Custom Event Colors

The widget uses ANSI color codes from iCalBuddy. To customize how these map to colors:

ansiColors: {
  31: '#ff0000',  // Red
  32: '#00ff00',  // Green
  34: '#0000ff',  // Blue
  // ... etc
}

Troubleshooting

Widget shows "iCalBuddy Not Found"

1. Check if iCalBuddy is installed:

   which icalBuddy
   

2. If not installed:

   brew install icalbuddy
   

3. If installed but widget can't find it, update the path in CONFIG.calendar.icalBuddyPath

No Events Showing

1. Check if you have events in Apple Calendar for the next 7 days

2. Test iCalBuddy directly:

   /opt/homebrew/bin/icalBuddy eventsToday+7
   

3. Make sure Übersicht has calendar access in System Settings > Privacy & Security > Calendars

Widget Not Updating

1. Refresh Übersicht from the menu bar (Übersicht > Refresh All Widgets)
2. Check the refresh frequency in config (it's in minutes)
3. Check macOS Console app for error messages from Übersicht

Testing Your Configuration

You can test the exact command the widget runs:

/opt/homebrew/bin/icalBuddy --configFile '' --separateByDate \
  --propertyOrder datetime,title --propertySeparators '|: |\n    |' \
  --excludeEndDates --noCalendarNames --sectionSeparator '' \
  --bullet '' --formatOutput --includeEventProps title,datetime \
  eventsToday+7

This shows exactly what the widget will display.

How It Works

1. Every refreshMinutes, Übersicht runs the iCalBuddy command
2. iCalBuddy fetches events from Apple Calendar and outputs them with ANSI color codes
3. The widget parses the output, groups events by day, and splits them into two columns
4. ANSI color codes are converted to styled HTML elements
5. React renders the final two-column layout on your desktop

Support

• For iCalBuddy issues:
  • iCalBuddy homepage
  • GitHub repo
• For Übersicht issues: Übersicht GitHub
• For widget-specific issues: Open an issue on Forgejo

Credits

Built with:

• Übersicht: Desktop widget framework
• iCalBuddy: Calendar data extraction