ChillPill-Shell

ChillPill-Shell is a lightweight, feature-rich dynamic pill bar for Hyprland, built with Quickshell. It's aimed squarely at users running without a dedicated GPU (like me) — eye candy that doesn't cost you a discrete card. Runs great on integrated graphics.

It runs as a standalone app: launch it from your terminal or app launcher when you want it, rather than having it baked into your session at all times. It's not bound to any dotfiles.

---

Resource Usage

• RAM: 200-500 MB (Average 400)
• CPU: Idle 0%, Average 3%, Min 0.1%, Max 10%
• GPU: Idle 0%, Average 15%, Min 6%, Max 40%

CPU and GPU usage varies with system. a better CPU and GPU use less.

My Hardware

• RAM: 8GB (DDR3)
• CPU: i5 3337U (Dual-core)
• GPU: Intel HD 4000 (Integrated)

---

Showcase

Watch the demo on YouTube

Main pill bar	Control center
Media playing popup	Notification popup (nusgmon-alert)
Cliphist (clipboard manager)	Mini dashboard — calendar
Mini dashboard — weather	Volume OSD (has more OSDs like brightness, battery, timer)
Spotlight	Control center — Wifi and Bluetooth panel
Wallpaper switcher	Cliphist — Full preview tab (Image; Text also supports)

Features (Pill States)

• Main Pill Bar - Battery, volume, workspaces, network, clock (default; customizable) — for more module options, see 'Know more' below.
• Control Center - Media player, buttons (WiFi, Silent Notifs, Timer, Bluetooth), volume & brightness sliders, notification stack
• Cliphist (Clipboard Manager) - Search (optional fuzzy search), clipboard image preview, item index status, multi select to delete many items at once (Shift + Up/Down range, Shift + Space pick, Del to delete), Tab to full preview the clipboard image/text
• Mini Dashboard - Profile image, username, hostname, uptime, battery, basic network info, today's data usage, datetime, weather, calendar, power buttons (lock, sleep, shutdown, reboot)
  • Calendar Popup - Previous/Next month buttons, event dates
  • Weather Popup - Feel, humidity, wind, sunrise & sunset, upcoming 2 days weather forecast, manual refresh button
• Spotlight - List of applications (Tab to read the long app description), optional fuzzy search for apps, web search (Tab to expand the full search url), math and shell commands run
• DBus Notification - App icon (optional), summary, body (YES! you can ditch swaync/dunst fully now)
• OSD - Battery, volume, brightness, timer
• Wallpaper switcher - A wallpaper switcher. . or CTRL + H to see hidden images (dot prefixed)
• Power Menu - 5 actions (Lock, Sleep, Logout, Restart, Shutdown) and action confirmation prompt

Know more

---

• Main pill bar modules has tooltips

• Extra modules available for the pill bar beyond the defaults: weather, bluetooth, vpn, notifications, brightness, audioVisualizer

• Pill bar supports custom modules (waybar-style) — run any command/script in the bar with format/tooltip templates, refresh intervals, streaming output and click actions (see Custom pill modules).

• 3 pill states are open-able with mouse:

  • Control center: Left click
  • Cliphist: Middle click
  • Mini Dashboard: Right click

  For the rest of states, you have to call the IPC through keybinds in Hyprland, which are provided in Keybinds section (including the mouse open-able states)

• DPI and Pill scaling is available in the config if you need it.

• Audio, workspaces, bluetooth and wifi in pill bar are clickable.

• Control center's media player progress bar is not only for status, it's usable to control the media you playing. also timer minutes can be change by right click and hold-to-burst (stop) it when running.

• The live audio spectrum (needs cava) is drawn in two independent flavours: bottom-anchored in the control center's media player (toggled by showAudioVisuals), and mirrored around its middle line (a wave instead of a skyline) -x as the audioVisualizer pill bar module (toggled by adding/removing it from pillModules). Either one can be used without the other.

• Control center has WiFi controller (panel) which has list of active networks and has password prompt.

• The wifi panel also includes the USB tethering toggle.

• Control center has also Bluetooth controller which has list of active, pair & connected devices/networks, device battery. here's 3 cases to connect a bluetooth device first time:

  • case 1: device wants a PIN or passkey typed in
  • case 2: device just wants us to display a code
  • case 3: device wants a yes/no confirmation of a shown passkey

• Cliphist shows image previews from ~/.cache/chillpill-shell/cliphist-imgs by converting image binaries into real images and save there. if you want these images cache to auto delete when you delete the cliphist (clipboard manager) image item, then there's deleteCliphistImgCache config option (enabled by default).

• In Cliphist full preview tab (which opens through Tab key), you can switch to other item by Up/Down keys, and can also delete the item from there. Full preview tab also shows previous/next item type (Image / Text) badges in bottom area, only if you toggle off the separatePreviewTabTypes (enabled by default).

• Cliphist items can be multi selected through keys, then deleted in one go with Del:

  • Shift + Up / Shift + Down: mark a range of items, editor style (grows and shrinks from where the range started)
  • Shift + Space: mark/unmark the item under the cursor (works in the full preview too, the marked count shows as a chip there)
  • Ctrl + Click / Shift + Click: same toggle with the mouse
  • Del: deletes the marked items, or the highlighted one when nothing is marked
  • Esc: drops the marks first, closes the panel on the second press

• Notifications, brightness and volume are able to show in slide animation (similar to iOS mute) while you playing video game or watching movie in full screen.

• Your today's data usage in mini dashboard is shown by nusgmon (i am the creator of it too).

• Wallpaper switcher shows you the filename of the image on hover. uses awww in backend to update the wallpaper by default (optional dep).

---

Configuration App

Raw config is still located at ~/.config/chillpill-shell/config.jsonc

Custom Pill Modules

Besides the built-in Quickshell modules (battery, workspaces, network, clock, vpn, notifications etc.), pillModules also accepts object entries that run any command/script and show its output in the bar — kind of similar to waybar's custom module.

Key	Description
run	Command to execute (required). Just pass the script name if it's in ~/.config/chillpill-shell/modules, else with leading ~ or absolute path
icon	Optional nerdfont icon, referenced in format/tooltip as {icon}
format	Text shown in the bar. Supports {text} / {tooltip} / {icon} placeholders. Default: {icon} {text} (or just {text} without an icon)
tooltip	Tooltip shown on hover. Supports {text} / {tooltip} / {icon} placeholders. Default: the output's tooltip
every	Refresh every N seconds. Omit (or 0) to run once at startup
stream	Keep the process running and update the module on every stdout line (true)
click	Command run on left click

The command may print plain text (used as {text}) or a JSON object per run / per line:

{ "icon": "", "color": "#6d9fd7", "text": "45°C", "tooltip": "45°C CPU Temperature" }

A sample script ship in the repo and get installed to ~/.config/chillpill-shell/modules/: cpu-temp.sh (one-shot CPU temperature, prints a temperature-dependent {icon, color, text, tooltip} JSON line). Scripts in that directory can be referenced by their plain file name, so "run": "cpu-temp.sh" works, scripts living anywhere else need a ~ path or an absolute one. Use your custom scripts to see specific/niche info in ChillPill-Shell's Pill Bar.

Dependencies

Note

Currently it's tested only on: Arch Linux and NixOS + Hyprland. Packages below are Arch's; find the equivalent for your distro.

• cliphist
• nusgmon (AUR package; non-Arch users can use the setup script instead)
• inotify-tools
• brightnessctl
• wl-clipboard
• pipewire
• blueman
• Qt Multimedia (qt6-multimedia on Arch)

Tip

install.sh auto-installs all of the above for Arch users, except these optional packages:

• Monocraft Font (ttf-monocraft-git / ttf-monocraft-nerd on AUR)
• JetBrainsMono Nerd Font (ttf-jetbrains-mono-nerd on Arch)
• qt6-imageformats (on Arch) more image format support (e.g. WEBP) for wallpaper previews
• holidays (Python lib) event dates in calendar; install.sh prompts to install this one

Tip

Holidays are configured under Weather & Data in the config app: Country picks the nation, Holidays is the master toggle, All categories includes every category the country supports, Categories takes a comma-separated list (e.g. public,optional), and Subdivision narrows it to a state/province code (e.g. MH). These map straight to calendar_events.py --all / --categories / --subdiv, and the cache filename changes with them so switching preferences never shows stale data.

• cava for showing audio visuals
• awww for wallpaper switcher if you don't use custom wallpaper script

Install

Tip

Use my Hyprland dotfiles, it's also made for No Dedicated GPU machines. You will get more better performance.

Arch users (AUR)

paru -S chillpill-shell

NixOS users (flake with Home Manager)

Add this repository as an input to your flake:

{
  inputs = {
    chillpill-shell = {
      url = "github:LUCKYS1NGHH/chillpill-shell";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}

Enable and configure it in your Home Manager configuration:

{ chillpill-shell, ... }:
{
  imports = [
    chillpill-shell.homeManagerModules.default
  ];

  programs.chillpill-shell = {
    enable = true;
    settings = {
      clockFormat = "HH:mm";
      # Other options from config.jsonc
    };
  };
}

Other

git clone --depth=1 https://github.com/LUCKYS1NGHH/ChillPill-Shell.git
cd ChillPill-Shell
chmod +x install.sh
sudo ./install.sh # use --skip-deps to skip dependencies installation (arch currently)

Uninstall?

---

AUR

paru -R chillpill-shell

Other

chmod +x uninstall.sh
sudo ./uninstall.sh

---

Auto startup

To auto-run at every time you start your Hyprland, paste this code in your ~/.config/hypr/hyprland.lua config file

hl.on("hyprland.start", function()
   hl.exec_cmd("chillpill-shell")
end)

Key Bindings

Keybindings are highly recommended for ChillPill-Shell in your Hyprland config. They call the shell's IPC to toggle its pill states — adjust the key combinations to your preferences.

State (IPC target)	Example Keybinds	Opens
controlCenter	MOD + CTRL + C	Media, sliders, buttons, notifications
cliphist	MOD + CTRL + V	Clipboard history
miniDashboard	MOD + CTRL + B	Profile, weather, data usage, calendar etc.
spotlight	MOD + D	Apps list to open, web search, math and basic shell run
wallpaperSwitcher	MOD + W	Wallpaper switcher
powerMenu	MOD + Escape	Power menu actions

MOD is the mainMod variable (typically SUPER key) from your config, e.g. hl.bind(mainMod .. " + D", hl.dsp.exec_cmd("qs ipc -p /usr/share/chillpill-shell call spotlight toggle")). On NixOS the command is chillpill-shell-ipc call <state> toggle instead of qs ipc -p /usr/share/chillpill-shell

qs ipc -p /usr/share/chillpill-shell call <target> <toggle|show|hide>

Tip

The config app can auto-paste these binds into ~/.config/hypr/hyprland.lua in one click — open the Keybinds page and press Auto paste keybinds.

---

Contributors

Thanks to the contributors who helped make the shell better, and special thanks to enhaoswen for the Wi-Fi controller backend for Quickshell.

Author

LUCKYS1NGHH / https://github.com/LUCKYS1NGHH/ChillPill-Shell