Skip to main content
Chronos Calendar is available as a native desktop application built with Electrobun, providing better performance, offline capabilities, and seamless integration with your operating system.

​
What is Electrobun?

Electrobun is a modern framework for building desktop applications:
  • Native Performance - Fast, responsive, and efficient
  • Cross-Platform - Works on macOS, Windows, and Linux
  • Small Footprint - Lightweight compared to traditional Electron apps
  • Modern Architecture - Built with Bun runtime for speed
The Chronos Calendar desktop app provides the same features as the web version with added benefits like native notifications, offline support, and system integration.

​
Installing the Desktop App

​
System Requirements

Before installing, ensure your system meets these requirements:
  • macOS 11.0 (Big Sur) or later
  • 64-bit Intel or Apple Silicon processor
  • 200 MB of available disk space
  • Internet connection for initial download and sync

​
Download and Installation

1

Download the Installer

Download the installer for your operating system from the releases page:
  • macOS - .dmg disk image
  • Windows - .exe installer
  • Linux - .AppImage or .deb package
2

Run the Installer

macOS:
  1. Open the downloaded .dmg file
  2. Drag Chronos Calendar to your Applications folder
  3. Eject the disk image
Windows:
  1. Run the downloaded .exe file
  2. Follow the installation wizard
  3. Choose installation location (default recommended)
  4. Click “Install”
Linux:
  1. Make the .AppImage executable: chmod +x Chronos-Calendar.AppImage
  2. Run the AppImage, or install the .deb package with your package manager
3

Launch the App

Open Chronos Calendar from:
  • macOS - Applications folder or Launchpad
  • Windows - Start menu or desktop shortcut
  • Linux - Application menu or by running the AppImage
4

Sign In

On first launch, you’ll see the login screen. Sign in with your Google account using the same OAuth flow as the web version.
On macOS, you may need to allow the app to run in System Preferences > Security & Privacy if you see a security warning on first launch.

​
Desktop Authentication

The desktop app uses a slightly different authentication flow:

​
How It Works

1

Click Sign In

Click “Sign in with Google” in the desktop app.
2

Browser Opens

Your default web browser opens to Google’s OAuth authorization page.
3

Authorize Access

Grant Chronos Calendar permission to access your Google Calendar.
4

Return to App

After authorization, you’ll see a “Redirecting to Chronos” page with options:
  • Open Chronos button - Click to return to the app
  • Try again button - Restart authentication if something went wrong
5

Automatic Redirect

If chronos:// URL handling is configured, the app opens automatically. Otherwise, click “Open Chronos” manually.
The desktop app callback page has a dark theme matching the native aesthetic. If the automatic redirect doesn’t work, simply click the “Open Chronos” button.

​
URL Protocol Handler

The desktop app registers the chronos:// URL protocol:
  • Allows the browser to automatically open the app after authentication
  • Enables deep linking to specific views or events
  • May require one-time system permission on first use
Troubleshooting URL handling:
If automatic redirects don’t work:
  1. Open System Preferences > Security & Privacy
  2. Allow Chronos Calendar to be the handler for chronos:// URLs
  3. Restart the app and try signing in again
If automatic redirects don’t work:
  1. Open Settings > Apps > Default apps
  2. Scroll to “Choose default apps by protocol”
  3. Find chronos:// and select Chronos Calendar
  4. Restart the app and try signing in again
If automatic redirects don’t work:
  1. Check your desktop environment’s URL handler settings
  2. Manually associate chronos:// with the Chronos Calendar executable
  3. Restart the app and try signing in again

​
Desktop App Features

​
Persistent Sessions

Unlike the web version, desktop app sessions persist:
  • Stay signed in - Remains authenticated across app restarts
  • Secure storage - Credentials stored securely using native OS keychains
  • Auto-refresh - Tokens are automatically refreshed in the background

​
Native Notifications

Receive desktop notifications for:
  • Upcoming events (coming soon)
  • Task reminders (coming soon)
  • Calendar sync updates (coming soon)
  • System-level alerts following OS notification standards
Notification features are planned for future releases. The infrastructure is in place in the desktop app.

​
Offline Support

The desktop app provides limited offline functionality:
  • View cached data - See recently loaded calendars and events
  • Create drafts - Add events and todos that sync when back online
  • Automatic sync - Changes sync automatically when connection is restored
While offline, you can view cached data, but creating or editing events requires an internet connection to sync with Google Calendar.

​
System Integration

  • Menu bar integration - Access app from the menu bar
  • Dock badge - Show unread counts or notifications
  • Touch Bar support - Quick actions on MacBook Pro Touch Bar (coming soon)
  • Spotlight integration - Search events from Spotlight (coming soon)

​
Development Mode

The desktop app includes development capabilities:

​
Running in Development

npm run dev
This command:
  1. Builds the Electrobun application
  2. Launches the app in development mode
  3. Enables hot reload for code changes
  4. Opens developer tools automatically
Development mode is only for developers building or customizing Chronos Calendar. Regular users should download the production builds from the official website.

​
Building from Source

# Development build
npm run build

# Production build
npm run build:prod
Builds are created in the Electrobun output directory with platform-specific installers.

​
Updating the Desktop App

Keep your desktop app up to date:

​
Automatic Updates (Coming Soon)

  • App checks for updates on launch
  • Notifies you when updates are available
  • One-click update and restart
  • Incremental updates for faster downloads

​
Manual Updates

Until automatic updates are implemented:
1

Check for Updates

Check the releases page to see if a newer version is available.
2

Download New Version

Download the latest installer for your operating system.
3

Install Update

Run the installer. On most platforms, it will automatically replace the old version.
You don’t need to uninstall the old version first. The installer handles the upgrade.
4

Restart the App

Launch the updated app. Your session and data are preserved across updates.

​
Performance and Optimization

The desktop app is optimized for performance:

​
Memory Usage

  • Efficient rendering - Only visible elements are rendered
  • Lazy loading - Data loads on demand
  • Resource cleanup - Automatic memory management
  • Optimized for long-running sessions

​
Startup Time

  • Fast cold start - Launches quickly even on first run
  • Instant warm start - Near-instantaneous restarts
  • Background loading - Data syncs after UI appears

​
Battery Life

On laptops, the desktop app is battery-friendly:
  • Minimal background activity when idle
  • Efficient sync scheduling
  • CPU throttling when not in focus
  • Dark mode support for OLED displays (coming soon)

​
Comparing Web vs Desktop

FeatureWeb AppDesktop App
InstallationNone requiredOne-time install
PerformanceGoodExcellent
Offline supportLimitedYes (with caching)
System integrationBasicFull native integration
Auto-updatesAlways latestComing soon
Platform availabilityAny browsermacOS, Windows, Linux
Session persistenceCookie-basedSecure native storage
NotificationsBrowser-onlyNative system notifications
Both versions provide the same core functionality. Choose the desktop app for better performance and native integration, or use the web app for instant access without installation.

​
Troubleshooting Desktop Issues

​
App Won’t Launch

If you see “Chronos Calendar can’t be opened because it is from an unidentified developer”:
  1. Open System Preferences > Security & Privacy
  2. Click “Open Anyway” next to the Chronos Calendar message
  3. Confirm you want to open the app
If Windows Defender SmartScreen blocks the app:
  1. Click “More info” in the SmartScreen dialog
  2. Click “Run anyway”
  3. The app will launch and this warning won’t appear again
If the AppImage won’t execute:
chmod +x Chronos-Calendar.AppImage
./Chronos-Calendar.AppImage

​
Authentication Problems

  1. Browser doesn’t open - Check default browser settings
  2. Redirect doesn’t work - Click “Open Chronos” button manually
  3. Already signed in on web - Sessions are separate; sign in again on desktop
  4. URL handler not working - See URL Protocol Handler section above

​
Sync Issues

  1. Check internet connection
  2. Verify you’re signed in (look for user profile in bottom-left)
  3. Check if Google account needs reauthorization
  4. Try signing out and back in
  5. Restart the app

​
Performance Issues

  1. App is slow - Restart the app to clear memory
  2. High CPU usage - Check for large calendar loads; try hiding unused calendars
  3. Crashes - Check for updates; file a bug report if persistent
  4. UI not updating - Refresh the view or restart the app

​
Data and Privacy

​
Local Data Storage

The desktop app stores data locally:
  • Session tokens - Encrypted in OS-native keychain/credential manager
  • Calendar cache - Stored in app data directory
  • User preferences - Stored in app configuration files
  • Todos - Synced with cloud but cached locally

​
Data Location

~/Library/Application Support/chronos-calendar/

​
Uninstalling

To completely remove Chronos Calendar:
1

Uninstall the App

macOS - Drag app from Applications to Trash Windows - Use “Add or Remove Programs” in Settings Linux - Delete the AppImage or uninstall the package
2

Remove Data (Optional)

Delete the data directory shown above to remove all cached data and preferences.
3

Revoke Access (Optional)

Visit Google Account permissions to revoke Chronos Calendar’s access to your Google account.

​
Best Practices

Keep App Updated

Check for updates regularly to get the latest features, performance improvements, and security patches.

Use Desktop for Daily Work

Install the desktop app if you use Chronos Calendar frequently. Better performance and offline support improve productivity.

Web for Quick Access

Use the web version when accessing from public computers or devices where you can’t install apps.

Report Issues

If you encounter bugs or problems, report them through the in-app feedback or GitHub issues to help improve the app.

​
Next Steps

Authentication

Learn about signing in and managing your session

Managing Calendars

Control calendar visibility and sync settings

Build docs developers (and LLMs) love

Get started for freeTalk to us