kyklos

The gestural, semantic, radial browser.

---

🌟 Introduction

kyklos (derived from the Greek κύκλος, meaning circle or wheel) is a modern, privacy-focused, glassmorphic Chromium-based browser shell built on top of Electron, React, and TypeScript.

Designed around the philosophy of "hidden chrome", Kyklos disappears completely until summoned, revealing its sleek controls through a fluid radial gesture (Alt wheel) or a powerful global Command Bar. It is engineered with robust, built-in ad-blocking, local Chrome extension compatibility, pure OLED dark modes, and AI-driven semantic vector search across your browsing history.

---

🚀 Key Features

• ⚡ Gestural Radial Menu (Alt hold): Hold the Alt key to trigger a glassmorphic circular menu mapping active tabs. Hover and release to select, duplicate, or close tabs instantly.
• 🔍 Semantic Vector Search: Find things by meaning rather than keywords. Searches are converted to vector embeddings via local AI, querying database history across conceptual definitions.
• 🛡️ Production-Grade AdBlocker: Full @ghostery/adblocker-electron engine compiled to a local cache (adblock_engine.bin), delivering BRAVE-level blocking of scripts, trackers, and popups.
• 🧩 Chrome Extensions Manager: Load and run standard unpacked Chrome extensions (unpacked directories containing manifest.json) stored and loaded persistently in SQLite database.
• 🕶️ Pure OLED Dark Theme: Live theme broadcaster syncing true pure black #000000 backgrounds across all active views (Tabs, URL bar, overlays, newtab views) to maximize energy efficiency.
• 💬 Glassmorphic Prompt Modals: Beautiful, Framer Motion-based prompt dialogues replacing standard native alert and confirm boxes.
• ⌨️ Unified Keyboard Suite: Full mapping of keyboard controls (e.g. Ctrl+Shift+T tab history restoring, Ctrl+T new tab, Ctrl+W close tab, Ctrl+R reloads, F12 DevTools).

---

🗺️ Architecture Overview

Kyklos uses a multi-view Electron layout containing layered overlays to optimize pointer event clicks and render frame updates cleanly:

graph TD
    A[Electron Main Process] -->|Spawns| B[Main BaseWindow]
    B -->|Layer 0| C[WallpaperView]
    B -->|Layer 1| D[Tab Views - WebContentsViews]
    B -->|Layer 2| E[ChromeView - Address/Tab Bar]
    B -->|Layer 3| F[OverlayView - Radial/Command Bar]
    
    A -->|IPC Bridge| G[Preload API - window.kyklos]
    G -->|Context Bridge| D
    G -->|Context Bridge| E
    G -->|Context Bridge| F

Loading

---

📂 Project Structure

kyklos/
├── build/                 # Desktop builder configurations & multi-res app icons (.ico, .icns)
├── resources/             # Static resource files (icon resources)
├── src/
│   ├── main/              # Electron Main process code
│   │   ├── ipc/           # IPC event handling and routing (router.ts)
│   │   ├── protocols/     # Custom kyklos:// scheme protocol handler (kyklos.ts)
│   │   ├── services/      # AdBlocker, Extensions registrar, SQLite, Vector search engines
│   │   ├── tabs/          # Tab view management class (Tab.ts, TabManager.ts)
│   │   └── window.ts      # Window creation & frameless frame metrics
│   ├── preload/           # Electron Preload contextBridge layer exposing APIs securely
│   ├── renderer/          # React + Vite client-side multi-view renderers
│   │   ├── chrome/        # Top address bar and tab strip view
│   │   ├── overlay/       # Radial gesture menu and Command bar view
│   │   ├── newtab/        # Glassmorphic home/newtab dashboard
│   │   ├── settings/      # Settings panel, extension page, and database controls
│   │   └── wallpaper/     # Dynamic background scenery generator
│   └── shared/            # Shared IPC contracts, constants, and database models

---

🛠️ Quick Start

Prerequisites

Make sure you have Node.js (v18+) and Python 3 installed (Python is required to compile native SQLite packages locally).

1. Install Dependencies

npm install

2. Run in Development Mode (Vite HMR + Electron)

npm run dev

3. Build & Package

# Package for Windows
npm run build:win

# Package for macOS
npm run build:mac

# Package for Linux
npm run build:linux

---

🤝 Contributing

We welcome contributions of all sizes! Please read our Contributing Guide to understand the branch structure, styling guidelines, and code of conduct before opening pull requests.

---

📜 License

This project is open-source and licensed under the MIT License.