✦ Overview ✦
A shell built to get things done.
Key goals:
Prefer Usability
Composable modules, design and appearance
nucleus-shell has been archived. There will be no longer support/development to it. End of story
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.
The rewrite was shutdown. The v2 branch and #46 are for only historical remarks.
✦ Previews ✦
Built with love
Forests
Passion Metallic
✦ Related Projects ✦
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 ✦
✦ 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 ✦
✦ License ✦
© 2025-PRESENT xZepyx — Licensed under the GNU GPL v3
评论