---

This is a NixOS Flake for Ax-Shell, providing a seamless and declarative way to integrate this beautiful shell into your NixOS configuration using Home Manager.

---

Screenshots

Features

This flake handles all dependencies and provides a fully declarative setup for Ax-Shell, including:

• Automatic Dependency Management: All required system and Python packages are handled by Nix.
• Declarative Configuration: Configure every aspect of Ax-Shell directly from your home.nix file.
• Home Manager Module: A comprehensive module with documented options for easy customization.
• Seamless Integration: Automatically generates necessary configurations for Hyprland, matugen, and theming.
• Reproducible Environment: Get the exact same shell setup on any NixOS machine.

Installation

Note

A working NixOS setup with Flakes and Home Manager is required.

1. Add the Flake to Your Inputs

Add Ax-Shell to your flake.nix inputs.

# flake.nix
{
  inputs = {
    # ... your other inputs
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";

    ax-shell = {
      url = "github:poogas/Ax-Shell";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}

2. Import the Home Manager Module

In your home.nix file, import the provided module.

# home.nix
{ inputs, ... }: {
  imports = [
    inputs.ax-shell.homeManagerModules.default
  ];
}

3. Enable Ax-Shell

Enable the shell in your Home Manager configuration.

# home.nix
{ pkgs, ... }: {
  programs.ax-shell = {
    enable = true;
  };

  # Ax-Shell needs Hyprland to run. See the integration guide below.
  wayland.windowManager.hyprland = {
    enable = true;
    # ... your hyprland settings
  };
}

Rebuild your system with nixos-rebuild switch --flake .#your-host, and Ax-Shell will be ready to use.

Configuration

All settings are managed declaratively under the programs.ax-shell.settings option set in your home.nix.

Here is an example demonstrating common customizations:

# home.nix
{ pkgs, ... }: {
  programs.ax-shell = {
    enable = true;
    settings = {
      # --- General ---
      terminalCommand = "alacritty -e";
      wallpapersDir = "/path/to/your/wallpapers";

      # --- Cursor ---
      cursor = {
        package = pkgs.oreo-cursors-plus;
        name = "oreo_black_cursors";
        size = 24;
      };

      # --- Bar & Dock ---
      bar = {
        position = "Top"; # "Top", "Bottom", "Left", "Right"
        theme = "Pills";  # "Pills", "Dense", "Edge"
      };
      dock.enable = false; # Disable the dock
      panel.theme = "Notch"; # "Notch", "Panel"

      # --- Keybindings ---
      keybindings.launcher = { prefix = "SUPER"; suffix = "SPACE"; };
    };
  };
}

Tip

For a complete list of all available options, please refer to the module file: nix/modules/home-manager.nix.

Note

For a complete, real-world example of how to integrate Ax-Shell with Hyprland and other desktop components, you can check out this reference configuration: https://github.com/poogas/nix-config

Integrations

Core Integration: Hyprland

Ax-Shell is not a standalone window manager; it is a comprehensive shell environment designed to run on top of Hyprland.

To make integration seamless, the NixOS module automatically generates the necessary Hyprland bind and exec-once directives. You can easily merge them with your personal configuration using the ++ operator.

# In your home.nix
{ config, ... }: {
  wayland.windowManager.hyprland = {
    enable = true;

    settings = {
      # ... your other Hyprland settings (monitors, animations, etc.)

      # --- Ax-Shell Integration ---
      # Use the '++' operator to merge Ax-Shell's binds with your own.
      bind = config.programs.ax-shell.hyprlandBinds ++ [
        # Add your custom keybinds here
        "SUPER, return, exec, alacritty"
        "SUPER, C, killactive,"
      ];

      # Merge Ax-Shell's startup commands with your own.
      exec-once = config.programs.ax-shell.hyprlandExecOnce ++ [
        # Your other startup apps
      ];
    };
  };
}

For a practical example, see this hyprland.nix module.

Screen Locking & Idle Management (hyprlock, hypridle)

Ax-Shell provides keybindings and UI elements for screen locking, but you need to configure the underlying tools. This setup integrates seamlessly with the theme generated by Ax-Shell.

# In your home.nix
{ config, ... }: {
  # Hyprland idle daemon
  services.hypridle = {
    enable = true;
    # ... your settings
  };

  # Hyprland screen locker
  programs.hyprlock = {
    enable = true;
    settings = {
      # This links hyprlock's theme to Ax-Shell's dynamic colors
      source = config.programs.ax-shell.hyprlandColorsConfPath;

      background = {
        path = config.programs.ax-shell.currentWallpaperPath;
        # ...
      };
    };
  };
}

See a working example for hypridle.nix and hyprlock.nix.

Launching Terminal Applications (xdg.terminal-exec)

To allow the Ax-Shell launcher to open terminal-based applications (like btop or neovim), you need to specify a default terminal emulator.

# In your configuration.nix or home.nix
{ pkgs, ... }: {
  xdg.terminal-exec = {
    enable = true;
    settings.default = [ "alacritty.desktop" ];
  };
}

You can see an example implementation in this terminal-exec.nix module.

SDDM Dynamic Theme

To sync your login screen wallpaper with your Ax-Shell wallpaper, use sddm-dynamic-theme.

1. Add the input to your flake.nix.
2. Enable it in your system configuration (configuration.nix).

   # configuration.nix
   { inputs, config, ... }: {
     imports = [ inputs.sddm-dynamic-theme.nixosModules.default ];
   
     services.sddm-dynamic-theme = {
       enable = true;
       username = "your-username";
       avatar.sourcePath = config.home-manager.users.your-username.programs.ax-shell.settings.defaultFaceIcon;
     };
   }

For an example of this setup, see this sddm.nix file.

NVIDIA Brightness Control

For brightness control to work correctly on NVIDIA desktop GPUs, you need nixos-ddcci-nvidia.

1. Add the input to your flake.nix.
2. Import the module in your system configuration (configuration.nix).

   # configuration.nix
   { inputs, ... }: {
     imports = [ inputs.nixos-ddcci-nvidia.nixosModules.default ];
     hardware.ddcci.enable = true;
   }

An example of this module can be found in this ddcci.nix configuration.

✨ Included Features

• App Launcher
• Bluetooth Manager
• Calculator
• Calendar
• Clipboard Manager
• Color Picker
• Customizable UI
• Dashboard
• Dock
• Emoji Picker
• Kanban Board
• Network Manager
• Notifications
• OCR
• Pins
• Power Manager
• Power Menu
• Screen Recorder
• Screenshot
• Settings
• System Tray
• Terminal
• Tmux Session Manager
• Update checker
• Vertical Layout
• Wallpaper Selector
• Workspaces Overview

Acknowledgements

A huge thank you to Axenide for creating the original Ax-Shell. This project is a NixOS-focused packaging and declarative integration of their amazing work.