Axenide/Ambxst

An Axtremely customizable shell.

---

Screenshots

---

Installation

curl -L get.axeni.de/ambxst | sh

This will install Ambxst and its dependencies. You will have the ambxst command available in your terminal, which you can use to start the shell.

Hyprland (more compositors coming soon!)

1. Run the installation command above.

2. Run ambxst install hyprland to add Ambxst's configuration to Hyprland. This will source a config file that applies Ambxst's settings. If you use hyprland.lua, or if no Hyprland config exists yet, it will look like this:

-- Ambxst
loadfile(os.getenv("HOME") .. "/.local/share/ambxst/hyprland.lua")()

-- OVERRIDES
-- Down here you can write or source anything that you want to override from Ambxst's settings.

If you only have hyprland.conf, Ambxst will keep using the legacy import there for compatibility:

# Ambxst
source = ~/.local/share/ambxst/hyprland.conf

# OVERRIDES
# Down here you can write or source anything that you want to override from Ambxst's settings.

As stated, anything you want to override from Ambxst's settings should be written under the "OVERRIDES" section.

1. Start Ambxst by running ambxst in your terminal. If you want to keep it running without having the terminal window open, you can run ambxst & disown. This will be only necessary for your first test run, as Ambxst will start automatically on login after step 2.

Ambxst is currently supported on Arch, Fedora, and NixOS. This means both based and derivative distributions.

[!IMPORTANT] The only pre-requisite is having Hyprland installed.

[!NOTE] For NixOS users, the screen recording utility gpu-screen-recorder will only be able to use the portal backend until you add programs.gpu-screen-recorder.enable = true; to your configuration.nix or home-manager.

NixOS + home-manager (Hyprland ≥0.56 Lua)

When you run Ambxst on NixOS with home-manager, do not configure Hyprland via wayland.windowManager.hyprland.settings with $mod / $terminal variables. Hyprland 0.56 expects a Lua entrypoint (hl.config(...), hl.bind(...), hl.exec_cmd(...)), not the legacy bind = "$mod, Return, exec, $terminal" syntax. The home-manager module generates hyprland.lua verbatim from settings, so the resulting file is invalid Lua.

Use a declarative xdg.configFile instead and let it loadfile() the file Ambxst writes:

# home.nix
{ lib, ... }: {
  wayland.windowManager.hyprland.enable = false;

  xdg.configFile."hypr/hyprland.lua".text = ''
    -- Import the config axctl/ambxst writes to ~/.local/share/ambxst/
    loadfile(os.getenv("HOME") .. "/.local/share/ambxst/hyprland.lua")()

    -- OVERRIDES (hl.* API, Hyprland >=0.56)
    hl.config({ input = { kb_layout = "latam", follow_mouse = 1 } })
    hl.monitor({ output = "", mode = "preferred", scale = 1 })
    hl.bind("SUPER + Return", hl.dsp.exec_cmd("kitty"))
    hl.bind("SUPER + Q",     hl.dsp.window.close())
  '';

  home.activation.fixHyprlandAmbxst = lib.hm.dag.entryAfter ["writeBoundary"] ''
    if [ -f "$HOME/.config/hypr/hyprland.conf" ] \
       && [ ! -L "$HOME/.config/hypr/hyprland.conf" ]; then
      mv "$HOME/.config/hypr/hyprland.conf" \
         "$HOME/.config/hypr/hyprland.conf.bak.$(date +%F-%H%M)"
    fi
    mkdir -p "$HOME/.local/share/ambxst"
    [ -f "$HOME/.local/share/ambxst/hyprland.lua" ] \
      || echo '-- placeholder' > "$HOME/.local/share/ambxst/hyprland.lua"
  '';
}

Notes:

• ambxst install hyprland detects home-manager-managed files (symlinks into /nix/store) and prints a guide instead of trying to append — it will never break the symlink or write through it.
• ~/.local/share/ambxst/hyprland.lua is regenerated by the axctl daemon on every theme/gaps/binds change. Cosmetic tweaks do not require nixos-rebuild; only structural changes (new binds, layout switch) need a home-manager switch.

---

Will this change my config?

Nope! Besides the Ambxst import block in your hyprland.conf or hyprland.lua, Ambxst is designed to be non-intrusive. It won't modify any of your existing configurations.

---

Features

• Customizable components
• Themes
• System integration
• App launcher
• Clipboard manager
• Quick notes (and not so quick ones)
• Wallpaper manager
• Emoji picker
• tmux session manager
• System monitor
• Media control
• Notification system
• Wi-Fi manager
• Bluetooth manager
• Audio mixer
• EasyEffects integration
• Screen capture
• Screen recording
• Color picker
• OCR
• QR and barcode scanner
• "Mirror" (webcam)
• Game mode
• Night mode
• Power profile manager
• AI Assistant
• Weather
• Calendar
• Power menu
• Workspace management
• Support for different layouts (dwindle, master, scrolling, etc.)
• Multi-monitor support
• Customizable keybindings
• Plugin and extension system
• Compatibility with other Wayland compositors

---

I need help!

If you are having trouble or have any questions:

• You can ask anything on Discord or in the GitHub discussions.
• You can open an issue on the GitHub repository.
• The main configuration is located at ~/.config/ambxst.

---

Credits

• outfoxxed for creating Quickshell and great documentation!
• end-4 for his awesome projects. I learned a lot from them! (And yoinked a lot of code, too. 😅)
• soramane for helping me when I started with Quickshell. (You probably don't remember, but still, heh.)
• tr1x_em for being a great friend and helping me find great tools. You rock!
• Darsh for not killing me when I left Fabric. u_u (Also for being a great friend and creating Fabric! Without Fabric, Ax-Shell wouldn't exist, so Ambxst wouldn't either. Thank you!)
• Mario for being a great friend and showing me Quickshell!
• Samouly for being Samouly. :3
• Brys for being his continuous support and for being a great friend!
• Zen for being a great friend and helping me when I started with Quickshell too!
• kh for being an awesome human being and listening to my delusions about Ambxst. :D
• And you, the user, for trying out Ambxst! You're awesome! 💖

(If I forgot someone, please let me know. 🙏)