Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
186 changes: 26 additions & 160 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,17 @@
*Agility Shell is a next-generation Wayland desktop shell powered by an ultra-fast Rust daemon (`agilityd`) and a GPU-accelerated Quickshell frontend. Featuring lightweight memory footprint (< 15MB daemon RSS), instant sub-15ms restarts, secure PAM session lock, iconic Doom Melt suite transitions, and 100% Rust & QML architecture.*
*Agility Shell is a next-generation Wayland desktop shell powered by an ultra-fast Rust daemon (`agilityd`) and a GPU-accelerated Quickshell frontend. Featuring lightweight memory footprint (< 15MB daemon RSS), instant sub-15ms restarts, secure PAM session lock, iconic Doom Melt suite transitions, dual theme engines (Agility Glass & Dynamic Material Theme), animated desktop layout presets, and 100% Rust & QML architecture.*

---

## Architecture Highlights
## Key Features

* **Next-Gen Rust Daemon (`agilityd`):** Multithreaded systems core communicating over high-speed D-Bus (`org.agility.Daemon`), delivering sub-2ms launcher responses, sub-4ms workspace switching, and isolated PAM worker threads.
* **Dual Theme Engine:** Switch between Default Glass UI and dynamic Material Design 3 theme with wallpaper-adaptive color schemes.
* **Desktop Layout Presets:** Instant animated switching between 'Full Material Canvas', 'Compact Island', and 'Bottom Waffle Bar' presets, plus custom user arrangements.
* **GPU-Accelerated Quickshell Frontend:** Declarative QML surfaces featuring liquid glass cards, interactive canvas applets with 20px grid-snapping, floating docks, toast notifications, sound effects, and OSD overlays.
* **Low Resource Footprint:** Combined memory under 40 MB RSS (down from 180MB+ in legacy Python), smooth 60 FPS on vintage hardware via `QT_QUICK_BACKEND=software`.
* **Iconic Transitions:** Staggered vertical column Doom Melt screen transitions across monitors when switching desktop suites.
* **Secure Wayland Session Lock:** Native `ext-session-lock-v1` / `WlSessionLock` integration with PAM rate limiting, exponential backoff, and blurred wallpaper backdrop.
* **High-Speed CLI (`agl`):** Lightning-fast command client written in Rust for full system control, sound effects, and status reporting.
* **Pure Rust & QML:** 100% free of Python runtime dependencies. All services, widgets, and applets run on native Rust and high-performance QML.

---

## Supported Window Managers

While agility shell does not manage window configurations itself, it connects natively to the following Wayland compositors:

| Window Manager | Status |
| -------------- | ------ |
| **Niri** | Stable |
| **Hyprland** | Beta |
| **MangoWM** | Beta |

---

Expand Down Expand Up @@ -61,158 +50,32 @@ curl -fsSL https://raw.githubusercontent.com/TattvaOrg/agility-shell/main/update
> - Update to Bleeding-Edge Main: `curl -fsSL https://raw.githubusercontent.com/TattvaOrg/agility-shell/main/update.sh | bash -s -- --main`
> - Or directly from terminal: `agl update`

### 4. Uninstall Agility Shell (One-Liner Complete Removal)
To completely remove Agility Shell from your system in one command:

```bash
# Total system removal (interactive prompts):
curl -fsSL https://raw.githubusercontent.com/TattvaOrg/agility-shell/main/uninstall.sh | bash

# Total removal + purge user configuration (~/.config/agility-shell) and caches:
curl -fsSL https://raw.githubusercontent.com/TattvaOrg/agility-shell/main/uninstall.sh | bash -s -- --purge
```
### 4. Uninstall Agility Shell
To uninstall Agility Shell, use `agl uninstall` or see the [Uninstallation Guide](more.md#uninstallation).

---

## Filesystem Layout & Architecture ("Where & Why")

Agility Shell follows standard Linux Filesystem Hierarchy Standards (FHS) and XDG base directory specifications to keep application code, dependencies, user data, and runtime logs cleanly decoupled.

| Location | Component | Purpose & Why It Lives Here |
| :--- | :--- | :--- |
| **`/usr/bin/`** or **`~/.local/bin/`** | `agl`<br>`agilityd`<br>`agility-shell` | **Executables & CLI**: Accessible directly from `$PATH`. `agilityd` is the background daemon, `agl` manages commands and metrics, and `agility-shell` launches the frontend session. |
| **`/usr/share/agility-shell/`** | Core Application QML & Assets | **Immutable Code & Assets**: Contains Quickshell QML files, sounds, SVGs, themes, and baseline configs. System updates upgrade the code without touching user settings. |
| **`~/.config/agility-shell/`** | User Configuration & Customizations | **Personal Settings**: Stores `config.json` (bar layout, widget ordering), `suits.json` (desktop presets), `wallpapers/`, and `config/niri.kdl`. Never overwritten by updates. |
| **`~/.config/systemd/user/`** | `agility-shell.service` | **Process Lifecycle & Autostart**: Systemd user unit tied to `graphical-session.target`. Provides automatic login startup, automatic crash recovery (`Restart=on-failure`), and unified log management. |
| **`~/.cache/agility-shell/`** | `shell.log` & Image Caches | **Ephemeral State & Logs**: Stores live session logs (`shell.log`), blurred wallpaper buffers, and temporary thumbnails. |

### Why This Separation Matters:
1. **Clean Updates**: Upgrading Agility Shell replaces only `/usr/share/` and `/usr/lib/`; your personal themes, suits, and bar layouts in `~/.config/agility-shell` remain untouched.
2. **Crash Resilience**: Systemd service management guarantees that if the compositor reloads or an applet hiccups, Agility Shell restarts automatically in the background.
3. **Multi-Environment Support**: The launcher automatically favors a local development checkout if run from a git clone, or falls back to system files when executed via systemd or CLI.

---

## CLI Management (`agl`)

Agility Shell includes a dedicated command-line interface `agl` installed to `/usr/bin/agl` (or `~/.local/bin/agl`) for easy lifecycle and maintenance management:

```bash
agl <command> [options]
```

| Command | Description | Example |
| :--- | :--- | :--- |
| `agl start` | Launch Agility Shell Next-Gen | `agl start` |
| `agl stop` | Cleanly stop daemon and Quickshell | `agl stop` |
| `agl restart` | Gracefully restart UI surfaces and daemon in < 15ms | `agl restart` |
| `agl status` | Inspect daemon PID, Quickshell PID, RSS memory, and D-Bus status | `agl status` |
| `agl lock` | Trigger exclusive Wayland session lockscreen | `agl lock` |
| `agl toggle <target>` | Toggle overlay surface (`launcher`, `notifications`, `canvas`, `suits`, etc.) | `agl toggle launcher` |
| `agl profile <action>` | Set or get system power profile (`balanced`, `performance`, `power-saver`, `get`) | `agl profile performance` |
| `agl suits <subcommand>` | Manage desktop suites (`list`, `next`, `prev`, `switch <id>`) | `agl suits next` |
| `agl bar <subcommand>` | Dynamically adjust status bar thickness (`height <26-48>`) or width mode | `agl bar height 36` |
| `agl bar-data` | Output instant status bar JSON metric snapshot | `agl bar-data` |
| `agl sound <action>` | Sound effects dispatcher (`list`, `play <name>`) | `agl sound play session-start` |
| `agl volume <action>` | Audio volume control (`up`, `down`, `mute` with optional step) | `agl volume up 5` |
| `agl brightness <action>`| Display backlight control (`up`, `down` with optional step) | `agl brightness up 10` |
| `agl screenshot <mode>` | Trigger screenshot capture (`full`, `window`, `region`) | `agl screenshot region` |
| `agl record <action>` | Screen recording management (`start [--with-audio]`, `stop`) | `agl record start --with-audio` |
| `agl caffeine` | Toggle Caffeine idle inhibitor state | `agl caffeine` |
| `agl deps` | Verify system runtime and compositor dependencies | `agl deps` |
| `agl update` | Check upstream repository and update Agility Shell | `agl update` |

### Vintage Hardware & Software Rendering
On machines without hardware Vulkan/OpenGL acceleration, run Quickshell with software rasterization for smooth 60 FPS performance:
```bash
QT_QUICK_BACKEND=software agl start
```

---

## Maintenance Scripts (`scripts/`)

All lifecycle scripts are organized inside the `scripts/` directory, with root wrappers maintained as backup forwarders for 100% backward compatibility:

| Script | Location | Purpose |
| :--- | :--- | :--- |
| `install.sh` | `scripts/install.sh` | Full system dependency check, Rust build, and system installation |
| `update.sh` | `scripts/update.sh` | In-place updater preserving user configs and wallpapers |
| `uninstall.sh` | `scripts/uninstall.sh` | Process termination, CLI cleanup, and configurable config removal |
| `start.sh` | `scripts/start.sh` | Launches Agility Shell via `agl start` or direct binary |
| `restart.sh` | `scripts/restart.sh` | Cleanly kills existing instances and relaunches in < 15ms |
## In-Depth Architecture & Reference Guide

Root backup scripts (`install.sh`, `update.sh`, `uninstall.sh`, `start.sh`, `restart.sh`) act as transparent forwarders to `scripts/*.sh` so automated curl commands and custom scripts continue working seamlessly.
For comprehensive documentation, filesystem specifications, CLI command references, and compositor autostart guides, refer to **[more.md](more.md)**:

---

## Uninstallation

To completely remove Agility Shell from your system (including running services, system binaries, desktop entries, sudoers charge limit rules, compositor includes, and matugen templates):

### One-Liner Removal (Remote)
```bash
# Standard interactive uninstallation:
curl -fsSL https://raw.githubusercontent.com/TattvaOrg/agility-shell/main/uninstall.sh | bash

# Complete purge (removes ~/.config/agility-shell, state, and caches without confirmation):
curl -fsSL https://raw.githubusercontent.com/TattvaOrg/agility-shell/main/uninstall.sh | bash -s -- --purge
```

### CLI or Local Repository
```bash
# Using CLI
agl uninstall
agl uninstall --purge

# Using in-tree / local script
./uninstall.sh
./uninstall.sh --purge
```

---

## Configuration & Autostart

Agility Shell can be managed via the systemd user service (recommended) or started directly by your Wayland compositor:

### 1. Systemd User Service (Recommended)
Agility Shell automatically enables its user service upon installation:
```bash
systemctl --user enable --now agility-shell.service
```

### 2. Compositor Integration (Guarded Fallback)
To ensure the shell is running while avoiding duplicate instances if systemd is already active, use the guarded launcher command:

#### Niri (`config.kdl`)
```kdl
include "~/.config/agility-shell/config/niri.kdl"
# Or standalone:
spawn-at-startup "bash" "-c" "systemctl --user is-active --quiet agility-shell.service || exec agility-shell"
```

#### Hyprland (`hyprland.conf`)
```ini
exec-once = systemctl --user is-active --quiet agility-shell.service || agility-shell
```

#### Modern Lua Config (`hyprland.lua`)
```lua
-- Add this to your exec or startup table
hyprland.exec_once({ "systemctl --user is-active --quiet agility-shell.service || agility-shell" })
```
* **[Architecture Highlights & Performance Targets](more.md#architecture-highlights)**
* **[Filesystem Layout & Architecture ("Where & Why")](more.md#filesystem-layout--architecture-where--why)**
* **[Complete `agl` CLI Command Reference](more.md#cli-management-agl)**
* **[Maintenance Scripts & Wrappers](more.md#maintenance-scripts-scripts)**
* **[Uninstallation Procedures](more.md#uninstallation)**
* **[Configuration & Compositor Autostart (Niri, Hyprland)](more.md#configuration--autostart)**

---

## Controlling Applets (IPC Syntax)

agility shell delegates keyboard shortcut assignments to your host window manager. You can toggle applets smoothly via an Inter-Process Communication (IPC) layer using `fabric-cli`:
Agility Shell delegates keyboard shortcut assignments to your host window manager. You can toggle applets smoothly via an Inter-Process Communication (IPC) layer using `agl toggle` or D-Bus:

```ini
# Example: Niri keybindings to toggle widgets
Mod+Space { spawn "fabric-cli" "exec" "agility-shell" "bar_manager.toggle('Launcher')"; }
Mod+N { spawn "fabric-cli" "exec" "agility-shell" "bar_manager.toggle('Notifications')"; }
# Example: Toggle surfaces via agl CLI
Mod+Space { spawn "agl" "toggle" "launcher"; }
Mod+N { spawn "agl" "toggle" "notifications"; }
```

```mermaid
Expand All @@ -235,13 +98,14 @@ subgraph group_daemon["Rust Daemon Core (agilityd)"]
node_sounds["Sound Engine<br/>org.agility.Daemon.Sounds"]
end

subgraph group_frontend["Quickshell QML Frontend (Minflair-based)"]
subgraph group_frontend["Quickshell QML Frontend"]
node_shell_qml["Quickshell runtime<br/>shell.qml"]
node_bar["Adaptive Status Bar<br/>Convex, Island & Gaming Styles"]
node_bar["Adaptive Status Bar<br/>Default Glass & Material Pill Styles"]
node_controlcenter["Control Center & Quick Settings<br/>Audio, WiFi, BT, Battery, System"]
node_launcher["App Launcher<br/>Fast Fuzzy Search & Filtering"]
node_lockscreen["Lockscreen & Auth<br/>PAM & Wallpaper Integration"]
node_settings["Personalization & Settings<br/>Themes, Fonts, Bar Style, Keybinds"]
node_settings["Personalization & Settings<br/>Themes, Material Mode, Presets, Fonts"]
node_desktop_canvas["Desktop Canvas & Widgets<br/>Clock, System Resources, Media Player, Notes"]
end

node_installer -->|"registers"| node_systemd
Expand All @@ -256,6 +120,7 @@ node_shell_qml -->|"renders"| node_controlcenter
node_shell_qml -->|"renders"| node_launcher
node_shell_qml -->|"renders"| node_lockscreen
node_shell_qml -->|"renders"| node_settings
node_shell_qml -->|"renders"| node_desktop_canvas
click node_agl "https://github.com/TattvaOrg/agility-shell/blob/main/crates/agility-cli"
click node_daemon "https://github.com/TattvaOrg/agility-shell/blob/main/crates/agilityd"
click node_startup "https://github.com/TattvaOrg/agility-shell/blob/main/agility-shell"
Expand All @@ -276,7 +141,7 @@ classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agl,node_startup,node_installer,node_systemd toneBlue
class node_bar,node_controlcenter,node_launcher,node_lockscreen,node_settings toneAmber
class node_bar,node_controlcenter,node_launcher,node_lockscreen,node_settings,node_desktop_canvas toneAmber
class node_daemon,node_compositor,node_telemetry,node_audio,node_lock_pam,node_notif_server,node_sounds toneMint
class node_shell_qml toneNeutral
```
Expand All @@ -288,5 +153,6 @@ class node_shell_qml toneNeutral
Contributions are always welcome! Please check the issues tab, follow our descriptive branching workflow, and submit a pull request.

Special thanks and attributions to:
- **[Minflair](https://github.com/t4lentles5/minflair)** : The modular Quickshell QML frontend architecture to use as a Agility's new rust + qml releses.
- **[dots-hyprland](https://github.com/end-4/dots-hyprland)**: For the magnificent Material You / Material Design 3 UI concepts, widget designs, and dynamic color styling.
- **[Minflair](https://github.com/t4lentles5/minflair)**: The modular Quickshell QML frontend architecture to use as Agility's new Rust + QML releases.
- **[caffyne-shell](https://github.com/caffyne-org/caffyne-shell)**: For foundational ideas and inspiration and python based desktop shell (Agility's older versions).
44 changes: 44 additions & 0 deletions crates/agilityd/src/modules/theme.rs
Original file line number Diff line number Diff line change
Expand Up @@ -752,6 +752,50 @@ impl ThemeService {
qs_cache.join("colorscheme.json"),
serde_json::to_string_pretty(&qs_colorscheme).unwrap_or_default(),
);

// Also synchronize Material 3 color tokens for Material Theme loader
let gen_dir = PathBuf::from(&home).join(".local/state/quickshell/user/generated");
let _ = fs::create_dir_all(&gen_dir);
let m3_colors = serde_json::json!({
"background": tokens.background_color,
"on_background": tokens.on_surface,
"surface": tokens.surface_color,
"surface_dim": tokens.surface_color,
"surface_bright": tokens.surface_container,
"surface_container_lowest": tokens.background_color,
"surface_container_low": tokens.surface_color,
"surface_container": tokens.surface_container,
"surface_container_high": tokens.surface_container,
"surface_container_highest": tokens.surface_container,
"on_surface": tokens.on_surface,
"on_surface_variant": tokens.outline,
"outline": tokens.outline,
"outline_variant": tokens.outline,
"primary": tokens.primary_color,
"on_primary": if tokens.is_dark { "#000000" } else { "#ffffff" },
"primary_container": tokens.surface_container,
"on_primary_container": tokens.primary_color,
"secondary": tokens.secondary_color,
"on_secondary": if tokens.is_dark { "#000000" } else { "#ffffff" },
"secondary_container": tokens.surface_container,
"on_secondary_container": tokens.secondary_color,
"tertiary": tokens.accent_colors.get(1).cloned().unwrap_or_else(|| tokens.secondary_color.clone()),
"on_tertiary": if tokens.is_dark { "#000000" } else { "#ffffff" },
"tertiary_container": tokens.surface_container,
"on_tertiary_container": tokens.secondary_color,
"primary_fixed": tokens.primary_color,
"primary_fixed_dim": tokens.primary_color,
"secondary_fixed": tokens.secondary_color,
"secondary_fixed_dim": tokens.secondary_color,
"error": "#ffb4ab",
"on_error": "#690005",
"error_container": "#93000a",
"on_error_container": "#ffdad6",
});
let _ = fs::write(
gen_dir.join("colors.json"),
serde_json::to_string_pretty(&m3_colors).unwrap_or_default(),
);
}

// 2. Render templates for terminals and Niri borders
Expand Down
Loading
Loading