Skip to content
jerbarooPublic

About

Shell for Hyprland written in QuickShell

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Foyer

Foyer is a Hyprland-specific QuickShell-based desktop shell with:

  • menu bar
  • notifications
  • on-screen display
  • application launcher
  • lock screen
  • plain-text viewer

Install

Foyer can currently only be installed via Home Manager.

  1. Add Foyer as an input to your configuration flake:
    inputs.foyer.url = "github:jerbaroo/foyer";
  2. Include the Home Manager module:
    homeConfigurations."your-user" = inputs.home-manager.lib.homeManagerConfiguration {
      inherit pkgs;
      modules = [
        inputs.foyer.homeManagerModules.default
        ./home.nix
      ];
    };
  3. Enable Foyer and configure its options. Required options are highlighted.
    programs.foyer = {
      accent = "#b4befe";
      font = {
        name = "Cascadia Mono";
        package = pkgs.cascadia-code;
        size = 18;
      };
      actions = {
        audioSettings = lib.getExe pkgs.pwvucontrol; # required
        bluetoothSettings = lib.getExe' pkgs.blueman "blueman-manager"; # required
        systemMonitor = "${lib.getExe pkgs.kitty} ${lib.getExe pkgs.btop}"; # required
      };
      animation = {
        enter = { curve = [ 0.215 0.61 0.355 1 ]; durationMs = 150; };
        exit = { curve = [ 0.215 0.61 0.355 1 ]; durationMs = 100; };
        resize = { curve = [ 0.34 1.08 0.22 1 ]; durationMs = 280; };
        slide = { curve = [ 0.215 0.61 0.355 1 ]; durationMs = 160; };
      };
      backgroundOpacity = 0.35;
      enable = true; # required
      iconTheme = {
        name = "Papirus-Dark";
        package = pkgs.papirus-icon-theme;
      };
      layout = {
        borderWidthPx = 2;
        launcherBorderWidthPx = 0; # defaults to borderWidthPx when omitted
        notificationBorderWidthPx = 0; # defaults to borderWidthPx when omitted
        notificationCenterBorderWidthPx = 0; # defaults to borderWidthPx when omitted
        cornerRadiusPx = 8;
        workspaceCornerRadiusPx = 4; # defaults to cornerRadiusPx when omitted
        gapPx = 16;
      };
      palette = {
        background = "#11111b";
        controlActive = "#313244";
        controlBorder = "#6c7086";
        controlHover = "#45475a";
        danger = "#f38ba8";
        fieldBackground = "#1e1e2e";
        notificationBody = "#f9e2af";
        panelBackground = "#181825";
        text = "#cdd6f4";
        textMuted = "#a6adc8";
      };
      search.port = 1235;
    };

Blur

Foyer exports read-only layer namespaces which you can target with blur rules. Make sure programs.foyer.backgroundOpacity is set to a suitable value. Also pay attention to the ignore_alpha value, it should be greater than zero and less than programs.foyer.backgroundOpacity.

Hyprland

wayland.windowManager.hyprland = {
  configType = "lua";
  extraConfig = let
    namespaces = "^(${lib.concatStringsSep "|" (builtins.attrValues config.programs.foyer.layers)})$";
  in ''
    hl.layer_rule({
        match = {
            namespace = ${builtins.toJSON namespaces},
        },
        blur = true,
        ignore_alpha = 0.001,
    })
  '';
};

Hyprglass

wayland.windowManager.hyprland.settings.layer_rule = [
  {
    blur = true;
    ignore_alpha = 0.001;
    match.namespace =
      "^(${lib.concatStringsSep "|" (builtins.attrValues config.programs.foyer.layers)})$";
  }
];

Control commands

The bar, launcher, and notification center support show, hide, and toggle. These commands control running instances; they don't start services. Hiding the bar keeps notifications, the OSD, and sleep/lock inhibitors running.

foyer bar hide
foyer launcher show
foyer notifications toggle

foyer text reads standard input to EOF and opens a scrollable plain-text panel. It preserves whitespace and displays markup literally. Press Escape or click outside the panel to hide it. The command sends the text to the running foyer-text service and returns immediately. Sending more text replaces the current content and opens the same overlay again.

printf 'SUPER + RETURN    Terminal\nSUPER + Q         Close window\n' | foyer text
foyer text < keybindings-help.txt

During development, start quickshell -p quickshell/text.qml inside nix develop, then pipe text to python cli.py text from another development shell.

foyer lock starts a minimal lock screen using the host's login PAM service. It covers every monitor and uses your shell's colours and font. Type your password and press Enter to unlock; Escape clears the field. Authentication failures keep the session locked and allow another attempt. The lock screen uses software rendering so it does not depend on OpenGL/EGL being available.

The bar's lock action uses this screen by default. Set actions.lockScreen to use another locker. For automatic locking, configure your idle daemon to run foyer lock. The host must provide /etc/pam.d/login for authentication.

The password outline uses the accent colour normally, the Caps Lock colour when enabled, and the error colour for the configured duration after each failure. Error feedback takes priority and does not delay the next authentication attempt. The outline width is configurable; zero hides it. Disabled input uses the disabled colour for its outline and text, with error feedback still taking priority on the outline.

programs.foyer.lockScreen = {
  borderWidthPx = 1;
  capsLockColor = "#f9e2af";
  disabledColor = "#a6adc8"; # defaults to palette.textMuted
  errorColor = "#f38ba8"; # defaults to palette.danger
  errorDurationMs = 3000;
};

To set a keybinding to toggle notifications use "${lib.getExe config.programs.foyer.package} bar toggle" in Home Manager keybindings.

Awake modes

“No sleep” holds a systemd sleep inhibitor. “No lock” holds a systemd idle inhibitor, pausing automatic locking and screen-off. Manual locking is still available. Your idle daemon must honour logind idle inhibitors; hypridle does so by default with ignore_systemd_inhibit = false.

Installed resources

Foyer installs its configuration under $XDG_CONFIG_HOME/foyer (normally ~/.config/foyer). Its user services are foyer-bar, foyer-launcher, foyer-server, and foyer-text. Layer namespaces use the foyer- prefix and are exported through programs.foyer.layers.

Development

Development environment

nix develop

Generates development settings automatically and configures the import path.

Bar and launcher

Run inside nix develop; it adds quickshell/dev-generated to QML_IMPORT_PATH so QML can find FoyerConfig and Cmds.

systemctl --user stop foyer-bar foyer-launcher
quickshell -p quickshell/bar.qml
# In another terminal, enter nix develop first:
quickshell -p quickshell/app_launcher.qml
# From a third dev shell, open the launcher:
foyer launcher show

Edit QML in the checkout; no rebuild is needed. After changing dev-settings.nix or templates, run nix run .#configure-dev or re-enter the dev shell. It writes Config.qml and Cmds under the ignored quickshell/dev-generated/ directory. Production files are unaffected. The launcher also needs the search server below.

Tests and linting

python cli.py --help
cargo test --manifest-path foyer-server/Cargo.toml
cargo clippy --manifest-path foyer-server/Cargo.toml

Formatting

qmlformat -i quickshell/bar/HoverPanel.qml
nixfmt configure-dev.nix defaults.nix dev-settings.nix flake.nix generate-settings.nix home-manager.nix options.nix

Search server

systemctl --user stop foyer-server
cargo run --manifest-path foyer-server/Cargo.toml -- --port 1235
# After exiting the development server:
systemctl --user start foyer-server

Server defaults to port 1235.

Wi-Fi interface

quickshell -p quickshell/nmtui.qml

Logs and services

journalctl --user -u foyer-server -f
journalctl --user -u foyer-bar -f
systemctl --user restart foyer-bar foyer-launcher

About

Shell for Hyprland written in QuickShell

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages