KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #open-source #ai #claude-code #codex #developer-tools #react #windows #deepseek-harness #ai-agent

ArchEclipse

★ 631 Open GitHub ↗

Highly polished, performance-focused Arch Linux + Hyprland dotfiles with dynamic theming, custom widgets, and a fast, modern workflow.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ArchEclipse

**A production-grade Hyprland desktop environment — built from scratch, engineered for daily use.**

[![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?logo=discord&logoColor=white)](https://discord.gg/fMGt4vH6s5)

[![Arch Linux](https://img.shields.io/badge/Arch_Linux-1793D1?style=flat-square&logo=arch-linux&logoColor=white)](https://archlinux.org/)
[![Hyprland](https://img.shields.io/badge/Hyprland-blue?style=flat-square)](https://hyprland.org/)
[![GTK4](https://img.shields.io/badge/GTK4-4A86CF?style=flat-square&logo=gtk&logoColor=white)](https://gtk.org/)
[![Python](https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org/)
[![Stars](https://img.shields.io/github/stars/AymanLyesri/archeclipse?style=social)](https://github.com/AymanLyesri/ArchEclipse/stargazers)
[![Issues](https://img.shields.io/github/issues/AymanLyesri/ArchEclipse?style=flat-square)](https://github.com/AymanLyesri/ArchEclipse/issues)

</div>

---

## What Is This?

ArchEclipse is my personal, battle-tested desktop configuration for Arch Linux + Hyprland. It's a **fully integrated system** that I use daily for coding, trading, gaming, and general productivity.

Every component was written, tuned, and iterated on over real-world use. The result is a cohesive environment where the UI, system utilities, automation scripts, and visual theming all work as a single product — not a patchwork of borrowed configs.

The project spans multiple languages and layers of the stack:

| Layer                              | Technologies                          |
| ---------------------------------- | ------------------------------------- |
| **UI / Widgets**                   | GTK4, TypeScript, TSX (Ags framework) |
| **Automation & Tooling**           | Python 3, Bash                        |
| **Performance-Critical Utilities** | C                                     |
| **Compositor**                     | Hyprland (Wayland)                    |

---

## Architecture & Technical Highlights

### Architecture

```mermaid
graph TB
 subgraph Install["Setup & maintenance"]
 Installer["install.py / update.py Python installer"]
 Pacman["pacman/pkglist.txt package list"]
 Archeclipse["archeclipse CLI update wrapper"]
 end

subgraph Hypr["Hyprland — window manager (Lua)"]
 HyprMain["hyprland.lua entry point"]
 HyprConfig["config/*.lua bind, animations, monitor, windowrule, gesture, input"]
 HyprScripts["scripts / scripts-c screenshot, screenrecord, hyprlock, wallpaper-loop"]
 WallpaperDaemon["wallpaper-daemon hyprpaper / mpvpaper"]
 Evremap["evremap key remapping service"]
 end

subgraph AGS["AGS / Astal shell (GTK4 + TypeScript)"]
 App["app.tsx shell bootstrap"]

subgraph BarSys["Bar system"]
 Bar["Bar.tsx state machine: compact/expanded/search/ volume/brightness/recording"]
 CompactBar["CompactBar.tsx"]
 ExpandedBar["ExpandedBar.tsx"]
 SearchBar["SearchBar.tsx"]
 BarSub["sub-components Battery, Volume, Bandwidth, Brightness, Player, Recording"]
 end

AppLauncher["AppLauncher.tsx Gtk.Popover launcher + QuickApps + AppHistory"]

subgraph Panels["Side panels"]
 LeftPanel["LeftPanel.tsx Settings, ChatBot, BooruViewer, MangaViewer, KeyBinds, UserProfile"]
 RightPanel["RightPanel.tsx Calendar, Notifications, SystemResources, Crypto, Waifu"]
 end

subgraph Core["Core layers"]
 Widgets["widgets/ reusable TSX components"]
 Services["services/ brightness, record, autoSwitchWorkspace"]
 Utils["utils/ settings-sync, auth-session, color, icon, notification"]
 Classes["class/ Supabase.class.tsx BooruImage.class.tsx"]
 Constants["constants/ + interfaces/ typed config & API contracts"]
 SCSS["scss/ bar, panel, widgets themes"]
 end

subgraph NativeScripts["Native/companion scripts"]
 CLoops["*.c loops system-resources, bandwidth, keystroke visualizer"]
 PyScripts["*.py chatbot, booru, manga, crypto, auth-callback"]
 ShScripts["*.sh get-wallpapers, translate, get-keybinds, image-color"]
 end
 end

subgraph Backend["External services"]
 Supabase[("Supabase auth + RLS + settings sync")]
 APIs[("Booru / manga / crypto / weather / chatbot APIs")]
 end

Installer --> Pacman
    Installer --> HyprMain
    Archeclipse --> Installer

HyprMain --> HyprConfig
    HyprConfig --> HyprScripts
    HyprConfig --> WallpaperDaemon
    HyprConfig --> Evremap
    HyprMain -- "spawns/execs" --> App

App --> BarSys
    App --> AppLauncher
    App --> Panels
    App --> Core

Bar --> CompactBar
    Bar --> ExpandedBar
    Bar --> SearchBar
    Bar --> BarSub
    SearchBar -.->|opens| AppLauncher

Widgets --> Core
    LeftPanel --> Widgets
    RightPanel --> Widgets
    BarSys --> Widgets

Core --> NativeScripts
    Utils --> Classes
    Classes -->|"auth, settings sync"| Supabase
    NativeScripts -->|"HTTP calls"| APIs

SCSS -.->|styles| App

classDef install fill:#EEEDFE,stroke:#534AB7,color:#26215C
    classDef hypr fill:#E1F5EE,stroke:#0F6E56,color:#04342C
    classDef ags fill:#FAECE7,stroke:#993C1D,color:#4A1B0C
    classDef core fill:#E6F1FB,stroke:#185FA5,color:#042C53
    classDef ext fill:#FAEEDA,stroke:#854F0B,color:#412402

class Installer,Pacman,Archeclipse install
    class HyprMain,HyprConfig,HyprScripts,WallpaperDaemon,Evremap hypr
    class App,Bar,CompactBar,ExpandedBar,SearchBar,BarSub,AppLauncher,LeftPanel,RightPanel ags
    class Widgets,Services,Utils,Classes,Constants,SCSS,CLoops,PyScripts,ShScripts core
    class Supabase,APIs ext
```

### Dynamic Theming Engine

A custom pipeline generates a full system color scheme from the active wallpaper at runtime using [Cwal](https://github.com/nitinbhat972/cwal) a custom C implementation of PyWal (10-50x faster, zero Python overhead) that generates a full color scheme at runtime. Colors propagate automatically to GTK4 widgets, terminal, and all UI components. No manual color editing required — ever.

- Per-workspace wallpaper assignment with both static and animated (video) support
- Global light/dark mode toggle with instant application across the entire environment
- Color changes hot-reload without restarting any component

### GTK4 Widget System (TypeScript/TSX)

All shell UI is built with the **Ags GTK4 v3** framework — replacing prior Eww and Ags GTK3 implementations. Widgets are written in TypeScript with TSX, enabling type-safe, component-based UI development that mirrors modern web frontend workflows.

The bar is fully modular — widgets are swappable at runtime. Current slots include:

- Workspace overview with live thumbnails
- Network bandwidth monitor
- Weather integration
- Media player (MPRIS)
- System tray
- Notification popups
- Live crypto price display

### Application Launcher (Rofi Replacement)

A custom-built launcher written in GTK4/TS replacing Rofi entirely, with built-in support for:

- App launching with fuzzy search
- Clipboard history browser
- Emoji picker
- Inline arithmetic evaluation
- URL forwarding to default browser
- Arbitrary custom command execution

### Panels

**Right Panel** — Configurable layout with swappable widgets: media player, notification history, calendar, script runner, crypto portfolio viewer, and an anime image viewer powered by the [Danbooru](https://danbooru.donmai.us) and [Gelbooru](https://gelbooru.com) APIs.

**Left Panel** — Power-user tools: an integrated chatbot (multi-API), a booru image browser, a manga reader ([MangaDex](https://mangadex.org/) API, WIP), live keybinds reference, and a Hyprland/Ags settings panel.

### Installer & Updater

The entire configuration deploys via a single command using a Python-based installer that handles dependency resolution, git-based dotfile deployment, and package management automatically. Post-install, the environment stays up to date with a single `archeclipse` command.

---

## Workspace Layout

| Workspace      | Assigned Application |
| -------------- | -------------------- |
| W2             | Browser              |
| W4             | Spotify              |
| W5             | Btop                 |
| W6             | Discord              |
| W7             | Steam / Lutris       |
| W10            | Games                |
| W1, W3, W8, W9 | General purpose      |

Applications launch automatically into their designated workspaces at login.

---

## Installation

**Requirements:** Arch Linux (or Arch-based), Hyprland configured and working, Python 3.

> All other dependencies are installed automatically by the installer.

### One-line Install

```bash
python3 <(curl -fsSL https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/refs/heads/master/.config/hypr/maintenance/install.py)
```

### Update

```bash
archeclipse
```

---

## Configuration Tips

- **User avatar:** `$HOME/.face.icon`
- **Wallpaper picker:** `SUPER + W`
- **Custom wallpapers:** `$HOME/.config/wallpapers/custom`
- **Custom Hyprland config:** `$HOME/.config/hypr/configs/custom`
- **Laptop users:** Install `upower` for battery monitoring
- **Full keybinds reference:** [keybinds.conf](https://github.com/AymanLyesri/ArchEclipse/blob/master/.config/hypr/configs/keybinds.conf) or via the Left Panel in-environment

---

## Roadmap

- [ ] Per-component tutorials and documentation _(in progress)_
- [ ] Gaming performance optimization _(in progress)_
- [ ] Continuous polish and refinement _(ongoing)_

Issues, suggestions, and feature requests are always welcome — [open one here](https://github.com/AymanLyesri/ArchEclipse/issues).

---

## Support

If this project saved you time or you just enjoy it, a coffee helps keep development going.

# ❤️ Support My Work

**₿ Bitcoin**

```txt
1JisW9xeatCFadtgsenjbpCcFePZGPyXow
```

</td>
<td align="center">

**Ξ Ethereum / BSC**

```txt
0x52d06d47bb9dc75eaf027f18cb197d5817989a96
```

</td>
</tr>
</table>

---

## Star History

[![Star History Chart](https://star-history.dera.page/svg?repos=aymanlyesri/ArchEclipse&type=Date)](https://star-history.dera.page/#aymanlyesri/ArchEclipse&Date)

---

## Visuals

### Application Launcher

![Application Launcher](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/app-launcher.png)

### Right Panel — Configurable Layouts

| Layout A                                                  | Layout B                                                  |
| --------------------------------------------------------- | --------------------------------------------------------- |
| ![Right Panel 1](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/right-panel-layout-1.png) | ![Right Panel 2](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/right-panel-layout-2.png) |

### Left Panel

| Chatbot                                           | Booru Viewer                                    |
| ------------------------------------------------- | ----------------------------------------------- |
| ![Chatbot](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/left-panel-chatbot.png) | ![Booru](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/left-panel-booru-1.png) |

| Settings                                            | Keybinds                                            |
| --------------------------------------------------- | --------------------------------------------------- |
| ![Settings](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/left-panel-settings.png) | ![Keybinds](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/left-panel-keybinds.png) |

### Wallpaper Switcher

![Wallpaper Switcher](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/wallpaper-switcher.png)

### Workspace Overview

![Workspace Overview](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/workspace-overview.gif)

### Theme Switching

| Dark Mode                              | Light Mode                               |
| -------------------------------------- | ---------------------------------------- |
| ![Dark](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/dark-theme.png) | ![Light](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/light-theme.png) |

### Keystroke Visualizer _(optional)_

![Keystroke Visualizer](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/keystroke-visualizer.gif)

### User Panel

![User Panel](https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/master/.github/assets/user-panel.gif)

ArchEclipse

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README