sud0-L/odyssey

odyssey is a Quickshell desktop shell for Hyprland built around a contextual system surface. It brings everyday controls, information, and workflows into one focused interface.

Minimal when idle. Informational when needed. Powerful when requested. Intelligent when useful.

odyssey is designed to integrate with your system, not take ownership of it.

You remain free to manage your own Hyprland configuration, shell, applications, packages, and system setup. odyssey provides the configuration and integration required for its desktop experience, while keeping user-owned configuration and system management in your control.

The installer supports preserving existing configuration, and files that odyssey needs to modify or replace are backed up before changes are made.

odyssey should be something you can build your setup around — not something that prevents you from making the setup your own.

odyssey's Dynamic Island stays compact at rest and expands contextually as you interact with the system.

It provides access to notifications, media, workspaces, device status, system controls, and focused OSD feedback for volume, microphone, brightness, and power changes without permanently occupying additional screen space.

Under Settings → Island & Motion, you can adjust the resting and hover layouts, including item spacing, hover outer-edge padding, and island height. The existing height remains the default. Floating and attached styles are available, with a reveal lip that follows the attached island's edges and chosen width.

The expanded Dashboard brings together time, weather, calendar, recent notifications, media, quick controls, and system information in one view.

Weather is unconfigured by default. Set your location under Settings → Dashboard to enable current conditions and forecasts.

Search and launch applications, switch Hyprland workspaces, or execute odyssey actions from a keyboard-friendly launcher and command palette.

The Command Launcher also lets you search and reuse your local shell command history.

Manage common desktop controls without leaving the shell, including:

• volume and microphone
• display brightness
• Wi-Fi and network information
• Bluetooth
• battery status
• power profiles
• do-not-disturb

odyssey provides its own notification service with contextual previews and notification history.

Active media is integrated directly into the island and Dashboard, providing playback information and controls without requiring a separate widget or panel.

Browse and apply wallpapers per monitor directly from odyssey.

odyssey uses Matugen to generate an adaptive color palette from your wallpaper and propagate it throughout the shell and supported desktop integrations for a cohesive appearance.

The wallpaper changes first, then its color palette follows shortly after. Generated palettes are cached per user, so selecting the same unchanged wallpaper again can be faster. The wallpaper refresh button gently pulses while a refresh is in progress.

odyssey currently includes:

• contextual Dynamic Island and system OSDs
• application launcher and command palette
• searchable shell command history
• Hyprland workspace integration
• Dashboard and system insights
• notification service and notification history
• media playback controls
• Wi-Fi and network controls
• Bluetooth controls
• audio and microphone controls
• brightness and power controls
• weather and forecasts
• calendar views
• locally saved notes
• wallpaper management
• Matugen-powered adaptive theming
• system monitoring
• configurable odyssey settings
• stable IPC commands for scripting and custom keybindings
• optional matching SDDM theme

odyssey currently targets Arch Linux with Hyprland and Quickshell.

Clone the repository and run the guided installer:

git clone https://github.com/sud0-L/odyssey.git
cd odyssey
./install.sh

The installer checks required dependencies, prepares the odyssey runtime, configures startup integration, installs odyssey's managed configuration, and creates backups before replacing existing files.

Managed mode may replace odyssey-managed configuration for components such as:

• Hyprland
• Hypridle
• Kitty
• Starship
• Fastfetch

Existing files are backed up before odyssey replaces or modifies them.

Zsh and Oh My Zsh are an optional enhancement. Interactive installs offer an explicit opt-in; non-interactive --yes installs do not enable it. To opt in non-interactively, use ./install.sh --yes --with-zsh. Bash, Fish, and other login shells do not require Zsh.

If you already have a configured Hyprland environment and want to retain your existing desktop configuration, choose preserve configuration in the guided installer or run:

./install.sh --preserve-config

Preserve mode keeps your existing configuration wherever possible while adding the integration required to run odyssey.

If the installer cannot safely determine the active Hyprland Lua config during an interactive install, it asks you for the config path. For non-interactive installs, or to select the path explicitly, set ODYSSEY_HYPRLAND_CONFIG to the absolute path of the Hyprland Lua config before running the installer.

odyssey exposes a stable IPC interface for shell actions.

For example:

odyssey ipc launcher toggle
odyssey ipc control-center toggle
odyssey ipc audio increment 3
odyssey ipc audio decrement 3
odyssey ipc audio mute
odyssey ipc audio micmute

These commands can be used from Hyprland keybindings, scripts, or other desktop integrations.

odyssey resolves its active runtime internally, so custom bindings do not need to reference versioned release directories or internal Quickshell paths.

odyssey provides its own freedesktop notification service. Running another notification daemon at the same time may cause conflicts.

Before modifying existing user-owned configuration, odyssey creates backups under:

~/.local/state/odyssey/backups/

Keep these backups while evaluating the beta, particularly if you install using managed configuration.

Weather is intentionally unconfigured on a fresh installation. Configure your location from Settings → Dashboard after odyssey is running.

odyssey includes a lifecycle manager for inspecting, maintaining, repairing, and updating an installation.

Public releases use human-readable versions such as 1.0.0-beta; the source identity is reported separately.

odyssey status
odyssey doctor

Both commands are read-only and can be used to inspect an installation without changing anything.

odyssey repair

repair restores odyssey-owned operational and lifecycle state for the currently installed release.

This includes activation links, the odyssey launcher, interrupted lifecycle operations, systemd units, services, and startup integration.

Repair does not reset preserved user configuration.

Changes require confirmation before they are applied.

odyssey config reset

config reset is intentionally separate from repair.

It backs up existing odyssey-managed configuration and restores the packaged defaults for the currently installed release. The installed release itself is not replaced.

Use this when you intentionally want to return odyssey's configuration to its default state.

Changes require confirmation before configuration is replaced.

odyssey update

The update lifecycle validates the candidate release and runtime dependencies before activation, activates the shell and lifecycle manager together, reconciles services, and retains the previous known-good release for rollback.

Updates are discovered from official odyssey GitHub Releases. odyssey displays the installed and available versions, asks for confirmation, and verifies the downloaded .ody artifact before activation. The previous known-good release is retained for rollback.

odyssey rollback

When a previous known-good release is available, odyssey can reactivate it using the existing lifecycle and activation infrastructure.

Additional commands are primarily intended for installation, development, recovery, or advanced management:

The backup, restore, startup, and component commands are currently reserved and are not exposed as functional public workflows.

If you have a heavily customized Hyprland setup, preserve configuration is recommended for your first installation.

You can then integrate odyssey into your existing environment without replacing the rest of your desktop configuration.

• Arch Linux
• Hyprland
• Quickshell
• systemd

Supported required dependencies are detected and installed by the odyssey installer. Quickshell is also checked at runtime so a stale binary that is incompatible with the current Qt version is detected before odyssey is activated. Optional enhancements are handled separately during guided installation when available.

Installations created before automatic GitHub Release discovery must run the installer once from a current checkout:

./install.sh --preserve-config

After that one-time manager upgrade, future releases can be installed with:

odyssey update

odyssey includes a matching SDDM theme under sddm/.

The SDDM theme is intentionally not installed automatically. Review and install it separately if you want a consistent odyssey login experience.

odyssey is under active development and feedback during the public beta is welcome.

When reporting an issue, please include:

• a description of the problem
• steps to reproduce it
• relevant terminal or journal output
• your Hyprland version
• your Quickshell version
• whether odyssey was installed using managed or preserve configuration

odyssey is a public beta.

The core desktop experience is functional, but some areas remain under active development and features or configuration may change between releases.

Expect occasional rough edges while the project matures.

odyssey is licensed under the GNU General Public License v3.0.