✦ nucleus-shell ✦

 

---

✦ Overview ✦

A shell built to get things done.

Key goals:

• Minimal, script-centric configuration
• Easy to review and selectively apply
• Composable modules for prompts, completions, and UI widgets

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.

---

✦ Previews ✦

Top Bar	Bottom Bar
Left Bar	Right Bar

---

✦ Related Projects ✦

• 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)

---

✦ 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 collection. The automated setup is conservative and will prompt before making destructive changes.

1. Install The Nucleus Cli:

   yay -S nucleus-cli

2. Run the installer:

   nucleus install

   • The installer will guide you through dependency checks and optional modules.

3. Open a fresh shell session or source your shell profile to apply changes.

Notes:

• Manual installation (symlinking files yourself) is supported and recommended for cautious users.
• 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 (if installed).
  • 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.

---

✦ To-Do ✦

• Redesign config layout and widget system for improved modularity and discoverability
• Add more curated optional modules and theme variants
• Improve installer prompts and backup behavior
• Add inbuilt-ai
• Improve support for multiple monitors (I do not have multiple monitors, I hope someone else will contribute and add these features)
• Add support for customizable bar per monitor
• Improve shell performance (currently a big laggy on my machine)

---

✦ 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 dots/.

• See license/CONTRIBUTING.md for full contribution guidelines.

• If you are a collaborator make sure to read license/COLLABORATORS.md

---

✦ Maintainer ✦

• Maintainer: xZepyx (Aditya Yadav)
• Contact: zepyxunderscore@gmail.com

---

✦ 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:

• end-4/dots-hyprland (Copied some services, took some design inspirations)
• etherealboi/twinshell (Some widgets)
• bgibson72/yahr-quickshell (A script that lists installed apps)
• caelestia-dots/shell (Didn't copy any code, but yoinked a lot of design from caelestia's vertical bar design)

---

✦ Thank You ✦

• @xr3tc: For helping me out on cli and lot of other web and stuff (and being a great friend)
• @end4: For his great projects. (I yoinked a lot of stuff)
• @ivan: Thanks bro for being our first "actual" contributor.
• @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 led me into hyprland shells for the first time.

---

✦ License ✦

© 2025 xZepyx (Aditya Yadav) — Licensed under the MIT License. See license/ for details.

---