✦ nucleus-shell ✦

June 29, 2026 · View on GitHub

✦ nucleus-shell ✦

        

✦ Overview ✦

A shell built to get things done.

Key goals:

  • Prefer Usability
  • Composable modules, design and appearance

Caution

nucleus-shell is soon going to be archived, it will no longer be maintained anymore and I'll be stopping any further development

Important

  • If you want to access the older releases refer to the archive branch
  • You can also join the discord server for help.
  • Before reporting an issue: If you encounter a problem in the current release, please first test against the latest source code by cloning the repository (git clone ...). This ensures you are not reporting an issue that has already been fixed. Only open an issue if the problem is still reproducible on the latest source.

Note

The rewrite was shutdown. The v2 branch and #46 are for only historical remarks.

✦ Previews ✦

Built with loveForests
PassionMetallic

✦ Related Projects ✦

Note

Note that any other repositories related to this project are community-made.

✦ Repository layout ✦

  • /quickshell/ — Primary shell
  • /license/ — License and contributing docs
  • /previews/ — Example screenshots used in this README
  • /install/ — Installer scripts and bootstrap utilities
  • /.github/ — README and other stuff

✦ Installation ✦

Follow these steps to install the shell. The automated setup is conservative and will prompt before making destructive changes.

Using the cli

yay -S nucleus-shell
nucleus install

Using the install script

git clone https://github.com/nucleus-hq/nucleus-shell
cd nucleus-shell/install
./unified.sh

Notes:

  • Manual installation (symlinking files yourself) is supported and recommended for cautious users.
  • Install Script is preffered over the cli installation.
  • Back up your existing dotfiles (e.g. ~/.config/ ~/.bashrc, ~/.zshrc, ~/.profile) before running the bootstrap.

✦ Configuration & customization ✦

  • Primary config: ~/.config/nucleus-shell/config/configuration.json
  • Modular settings: prompt, completion, and widget modules are separated for easy replacement.
  • To customize:
    • Edit the primary config or use the provided settings app.
    • Enable/disable modules by editing the module list in the ~/.config/quickshell/nucleus-shell/shell.qml file.

✦ Recommended environment ✦

  • Compositor: Hyprland
  • Terminal: Kitty
  • Fonts: JetBrainsMono

✦ Troubleshooting ✦

  • Missing/Unloaded Modules:
    • Ensure the module file is loaded in the correct order. Check ~/.config/quickshell/nucleus-shell/shell.qml.
  • Broken visuals:
    • Check ~/.local/share/nucleus/user/config.json
  • Slow startup:
    • Disable unused modules or lazy-load heavy features (e.g., prompt segments that query network/state).
  • Conflicting user configs:
    • Inspect existing profile files (~/.bashrc, ~.zshrc, ~/.profile, ~/.config) before applying changes.
  • Installer failures:
    • Re-run the installer with verbose output or check install/ scripts for dependency checks.
  • Cli Commands
    • To update: nucleus update The cli will guide you through the update.
    • To uninstall: nucleus uninstall The cli will automaticly uninstall the shell.
    • To stop/kill the shell: nucleus kill or nucleus stop
    • To switch themes: nucleus switch theme <themename>
    • More at: cli-documentation

✦ To-Do ✦

✦ Weird Tentacles ✦

Star History Chart

✦ Contributing ✦

Contributions are welcome. When contributing:

  • Open concise issues after confirming the problem isn't caused by local configuration.

  • Submit focused PRs with clear descriptions and tests where applicable.

  • Follow code structure and naming conventions used in the codebase.

  • See CONTRIBUTING.md for full contribution guidelines.

✦ Maintainer ✦

✦ Acknowledgments ✦

  • QuickShell and its contributors
  • Hyprland and its developers/contributors

✦ Inspiration / Copying ✦

I did copy some code from other repositories and took design inspirations which are listed here:

✦ Thank You ✦

  • @ivan: Thanks bro for being the first contributor. :P
  • @Tanujairamv: For being a great friend and contributing to the project and the community. <3
  • @Saturno: For being a great friend and contributing to the project and the community. ;)
  • @end4: For projects like illogical-impulse, You can get a lot of quickshell reference.
  • @soramanew: We haven't talked but I was greatly inspired by his project caelestia-shell.
  • @Axenide: I also haven't talked to him but his project Ax-Shell got me into hyprland shells. Probably.

✦ Team/Project Members ✦

  • @xZepyx: Founder & Former Maintainer

  • @TanujairamV: Material UI Developer & Designer

  • @Saturno: Logical Developer

  • None of us ^ are working on this project anymore.

✦ Fella Contributors ✦

Contributors

✦ License ✦

© 2025-PRESENT xZepyx — Licensed under the GNU GPL v3