What is Cosmic-light?

Cosmic-light is an innovative, open-source application that recreates the highly acclaimed Dynamic Island interface, originally popularized by Apple devices, for the Windows operating system. It functions as a centralized, visually stunning control hub that elegantly sits on your screen, providing immediate access to critical information and controls without cluttering the desktop.

This tool transforms passive desktop space into an interactive zone, offering fluid, physics-based animations and a liquid-smooth user experience. It consolidates essential utilities—from media playback management and real-time weather updates to smart calendar notifications and integrated AI assistance—into one cohesive, customizable module. Cosmic-light aims to enhance user productivity and desktop aesthetics simultaneously by merging high-end design with practical functionality.

Key Features

Cosmic-light is packed with features designed for modern desktop users:

• 🏝️ Dynamic Island UI:
  • Positioning flexibility: Place the island elegantly at the Bottom or Middle of your screen.
  • Intelligent expansion: The island expands fluidly only when needed, showing Time, Date, and Active Window status on the Home view.
  • Advanced Animations: Utilizes framer-motion and liquid-glass-react for high-quality, physics-based visual feedback.
• 🎵 Media Control Integration:
  • Seamlessly manages playback (Play, Pause, Next, Previous, Volume) for applications like Spotify and system audio.
  • Real-time Audio Visualizer that reacts dynamically to music.
  • Displays rich metadata including massive album art, artist information, and track progress.
  • Smart Icon detection identifies the source application (Spotify, YouTube, Chrome) and output device.
• 🌦️ Live Weather Visualization:
  • Atmospheric display featuring real-time particle rendering (rain, snow, clouds, stars).
  • Provides detailed statistics: Temperature, Wind speed, Humidity, and Precipitation chance.
  • Instant alerts for severe weather warnings.
• 📅 Smart Calendar Sync:
  • Integrates with Google Calendar via a private iCal link.
  • Proactive Notifications: The island automatically expands 5 minutes before an event starts.
  • Includes a full, interactable Month View.
• 🧠 AI Intelligence Hub:
  • Gemini Mode: Built-in chat interface powered by Google's Gemini AI, supporting Markdown, Code blocks, and KaTeX math rendering.
  • Perplexity Mode: Real-time web search integration complete with citations and sources.
  • Context-Aware: Conversation history is stored locally for continuity.
• 🔒 Local First & Secure: All user data, including API keys, is stored and encrypted locally on the user's machine.
• ⚙️ Extensive Customization: Control opacity, set the "Stayback" time (auto-collapse delay), and manage placement across multi-monitor setups.

How to Use Cosmic-light

Getting Cosmic-light running on your Windows machine involves a few straightforward steps, leveraging Node.js and Python for the necessary system bridges:

1. Prerequisites Check: Ensure you have Node.js (v20 or higher) and Python (v3.10 or higher) installed on your system.
2. Installation: Clone the repository from GitHub and navigate into the directory:

git clone https://github.com/uspraveen/Cosmic-light.git cd Cosmic-light

3.  **Dependency Setup:** Install the frontend dependencies using npm and the backend dependencies (required for system data bridging) using pip:
    ```bash
npm install
pip install -r requirements.txt

1. Running Locally: Start the application development server:

npm run dev

5.  **Configuration:** Once running, click the Dynamic Island icon to expand it, then access the Settings Gear. Here, you must input your personal API keys (Gemini/Perplexity) and paste your Google Calendar iCal link to unlock the full feature set.
6.  **Building:** To create a standalone, distributable `.exe` installer for Windows, run `npm run build`. The final installer will be available in the `release/` directory.

## Use Cases

Cosmic-light is ideal for users seeking to maximize desktop efficiency and visual appeal:

1.  **The Multitasker/Developer:** Quickly check calendar alerts without switching focus from coding, manage Spotify playback instantly, and use the integrated AI chat for rapid context lookups or debugging assistance, all from a single, non-intrusive UI element.
2.  **The Media Enthusiast:** Users who frequently stream music or video benefit from the real-time visualizer and precise media controls, ensuring they never miss a track change or need to hunt for the volume slider.
3.  **The Information-Driven Professional:** Professionals needing constant awareness of local conditions can utilize the live weather module, ensuring they are prepared for sudden weather shifts without opening a browser tab.
4.  **The Productivity Minimalist:** Individuals aiming for a clean desktop environment can consolidate multiple widgets (clock, weather, calendar reminders) into the compact, auto-hiding Dynamic Island, maintaining focus while staying informed.
5.  **The Customization Advocate:** Users who enjoy tailoring their digital workspace can leverage the positioning, theming, and multi-monitor support to perfectly integrate the island into their unique setup.

## FAQ

**Q: Is Cosmic-light compatible with macOS or Linux?**
A: Cosmic-light is specifically developed as a control center for the **Windows** operating system, utilizing Electron and Python bridges tailored for Windows system interaction.

**Q: Do I need to pay for the AI features?**
A: The Cosmic-light application itself is open-source and free. However, utilizing the Gemini or Perplexity AI modes requires you to provide your own valid API keys from Google AI Studio or Perplexity.ai, respectively, for which usage fees may apply based on the provider's pricing structure.

**Q: How secure is my data, especially my API keys?**
A: Cosmic-light prioritizes user privacy. It operates on a local-first principle, meaning all configuration data and API keys are stored and **encrypted** directly on your local machine, never transmitted to the developers.

**Q: What happens if I don't install Python?**

A: Python (v3.10+) is a mandatory prerequisite. The application relies on Python scripts to establish system bridges necessary for fetching real-time data like active media controls and detailed weather statistics. Without it, core functionality will be unavailable.

**Q: Can I change where the Dynamic Island appears on my screen?**
A: Yes. Through the in-app settings (accessed via the gear icon after expanding the island), you can choose to position the island at the **Bottom** or the **Center** of your primary display, or select a specific monitor if you use a multi-monitor setup.