REPOSITORY OVERVIEW

Live repository statistics

★ 743Stars

⑂ 16Forks

◯ 0Open issues

◉ 743Watchers

README preview

✦ nucleus-shell ✦

A shell built to get things done.

Key goals:

Prefer Usability
Composable modules, design and appearance

[!CAUTION] nucleus-shell has been archived. There will be no longer support/development to it. End of story

[!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.

Built with love	Forests

Passion	Metallic

nucleus-cli: CLI for nucleus-shell
nucleus-plugins: Plugins for nucleus-shell
nucleus-colorschemes: Colorschemes for nucleus-shell
zenith: Intelligence backend for nucleus-shell (required to use intelligence)

[!NOTE] Note that any other repositories related to this project are community-made.

/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

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.

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.

Compositor: Hyprland
Terminal: Kitty
Fonts: JetBrainsMono

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

Read Todo.md

✦ Weird Tentacles ✦

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: xZepyx
Contact: zepyxunderscore@gmail.com

QuickShell and its contributors
Hyprland and its developers/contributors

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

end-4/dots-hyprland (Copied some services, took some design inspirations)
etherealboi/twinshell (Some widgets)
caelestia-dots/shell (Didn't copy any code, but yoinked a lot of design from caelestia's vertical bar design)

@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.

@xZepyx: Founder & Former Maintainer
@TanujairamV: Material UI Developer & Designer
@Saturno: Logical Developer
None of us ^ are working on this project anymore.