# mechabar: a modular Waybar configuration you clone into place

> mechabar packages a Waybar status bar for Hyprland and Arch setups as shell scripts, JSONC modules and Catppuccin themes that you install by cloning the repository over your own config directory. It is quick to try and quick to undo, but every module assumes kitty, and the project publishes no releases.

**sejjy/mechabar** — A modular Waybar configuration

- Repository: https://github.com/sejjy/mechabar
- Stars: 875 · Forks: 76
- Language: Shell
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/sejjy-mechabar

## A Waybar panel split into scripts, modules and stylesheets

mechabar is not a plugin or a theme pack in the usual sense. It is a complete Waybar configuration laid out as a small tree of files that you place in your home directory, and the layout is visible from the repository root: LICENSE, README.md, assets/, config.jsonc, install, modules/, scripts/, style.css and themes/. The primary language is Shell, which tells you where the real logic lives. The panel itself is described in config.jsonc, individual pieces of it live under modules/, and the shell helpers that back the click handlers live under scripts/.

That separation is the whole point of the project. Rather than one large JSON file that a user has to reverse engineer, the setup can be opened one module at a time. The modules folder is also where custom modules are meant to go, which means a user adding their own entry is following the structure the author intended rather than inventing one. The themes folder holds stylesheets that style.css imports, and assets/ holds the preview images used in the documentation.

The topics attached to the repository, arch-linux, catppuccin, hyprland and waybar, tell you the intended environment. Nothing in the documentation, however, restricts the configuration to Hyprland. Waybar itself is the only hard requirement listed, plus a terminal.

## The install step renames your own config directory out of the way

Installation is three commands, and the order matters. The documentation asks you to move any existing Waybar configuration aside before cloning, because the clone target is the same directory that Waybar reads from.

```bash
mv ~/.config/waybar{,.bak}
git clone https://github.com/sejjy/mechabar.git ~/.config/waybar
~/.config/waybar/install
```

The first line uses brace expansion to turn ~/.config/waybar into ~/.config/waybar.bak, which leaves the old configuration one directory up rather than deleted. The second line puts the repository exactly where Waybar expects to find its configuration. The third runs the install script that sits in the repository root, and the documentation says that this step installs the dependencies and restarts Waybar, with the dependency list living in the install file itself.

Two things are worth checking before you run it. The install script is executed, not inspected, so a reader who wants to know what it will do has to open that file first. And because the clone overwrites the target directory path, any files you had added to ~/.config/waybar yourself are only safe if the rename succeeded. The backup name is fixed at .bak, so a second installation overwrites the first backup.

## Every module assumes kitty, and the fix is a manual search

mechabar assumes the kitty terminal. The documentation lists a terminal as a requirement, names kitty as the default, and then explains the consequence plainly: if you use a different terminal, you need to replace all invocations of kitty in the module files. The example it gives edits a power module and swaps the command.

```jsonc
// ~/.config/waybar/modules/custom/power.jsonc

"custom/power": {
	// "on-click": "kitty -e ~/.config/waybar/scripts/power",
	"on-click": "ghostty -e ~/.config/waybar/scripts/power",
}
```

The example keeps the original kitty line as a comment, which is a reasonable way to mark the thing you are meant to change. What it does not give you is a single setting or variable that switches terminals in one place. The change is a find and replace across files under modules/, and every module that launches a script has to be found by hand. A user on kitty does nothing. A user on ghostty, foot, or any other terminal does the work, and the documentation does not say how many such invocations there are.

The same applies to the scripts directory. Since the scripts are the payloads that the click handlers launch, and the click handlers are what reference kitty, the terminal assumption leaks into every interactive part of the bar.

## Themes change through a single import in style.css

The visual side is handled the same way as the rest: one file is the entry point. style.css is the file Waybar loads, and switching theme means importing a different stylesheet from the themes directory into it.

```css
/* @import "themes/catppuccin-mocha.css"; */
@import "themes/catppuccin-latte.css";
```

The commented-out line is the default. Four Catppuccin variants are shown in the documentation, Mocha as the default, with Macchiato, Frappe and Latte also available. The mechanism is plain CSS import, so the choice of which variant becomes active is literally which line you uncomment, and switching back means reversing the edit.

The icons follow the same hand-edited philosophy. Most modules use nf-md- icons from Nerd Fonts, and the documentation points at the Nerd Fonts cheat sheet for finding more. It also warns that different fonts render characters at different sizes, which can affect the layout, and that a different font may require adjusting the font sizes in style.css. That is a real maintenance edge: an icon theme change is not isolated from the stylesheet, so a user who swaps fonts inherits a layout that may need manual tuning.

## The leftmost module slot is deliberately left empty

One part of the bar belongs to the user. The documentation states that the leftmost module is left for you to configure, and gives a shape for it.

```jsonc
// ~/.config/waybar/modules/custom/user.jsonc

"custom/user": {
	"on-click": "/path/to/your/script", // Run your own script
	"on-click-right": "pkill -SIGUSR2 waybar", // Restart Waybar
}
```

Two behaviours are demonstrated. The left click runs a script of your choosing, at a path you fill in, and the right click sends SIGUSR2 to the waybar process to restart it. That restart trick is worth noting on its own, because it is the fastest way to apply a change to config.jsonc or to a module without leaving the compositor.

The design is honest about who owns what. The project provides the fixed modules, and the first slot is a blank space with two documented hooks. There is no example of a genuinely useful module to copy, so a user has to supply their own script. The path placeholder makes that explicit rather than pretending the module is finished.

## No releases, no dependency list in the documentation, no rollback notes

Several things a user would look for are simply absent. The repository has no GitHub releases, so there is no numbered version to pin and no changelog to read. The last push was on 2026-10-15, and there is a single branch of work rather than a tagged history. Upgrading in practice means pulling the main branch and accepting whatever changed, and the documentation does not describe any upgrade or rollback procedure for a user who has edited the module files locally.

The dependency list is the other gap. The documentation says to see the install file for the list of dependencies, which means the exact package names live in a script rather than in prose. A user on a distribution that names packages differently, or one that wants to review before running, has to open the script and read it. The project lists waybar and a terminal as the requirements and stops there.

The licence is MIT, which is permissive and simple for a configuration someone is likely to edit in place. For a project whose whole workflow is to clone into a directory you own and then modify, that is the practical licence choice, and it means your local edits and the upstream files can sit in the same tree without friction.

## Where mechabar sits against writing a Waybar config yourself

The realistic alternative is to write your own config.jsonc. Waybar is a program that reads a configuration file and draws modules; nothing in it requires a repository of scripts and themes. The difference in approach is that a from-scratch config is a single artifact you own outright, while mechabar is a working example you adopt and then diverge from, carrying the shell scripts and the module layout with it.

What you gain from mechabar is the parts that are tedious to build first: a set of modules that already click through to scripts, a stylesheet with the Catppuccin palette applied, and a working install path. What you take on is the shape of somebody else's decisions, including the kitty assumption and the Catppuccin default, and the job of re-reading a repository whenever you want to change something structural.

For the specific case of a Hyprland user on Arch who wants a bar that already looks finished, that trade is usually worth it. For a user who only needs a clock, a battery indicator and a workspace switcher, the whole repository is heavier than the task. The fork point is simple: clone it, then decide whether the leftmost module slot is where your own script belongs.

## Conclusion

mechabar suits an Arch or Hyprland user who wants a finished Waybar panel and is willing to edit shell scripts and JSONC by hand. It does not suit someone who wants a maintained upstream release or a terminal-agnostic package, since the modules hardcode kitty and the repository has no GitHub releases. Verify first that the install script in the repository root only installs the dependencies it lists for your distribution, and keep the ~/.config/waybar{,.bak} rename in place until your own modules are in place.

## FAQ

### What exactly does mechabar provide for Waybar?

It provides a complete Waybar configuration: config.jsonc for the panel itself, a modules directory with individual module definitions, a scripts directory with the shell helpers those modules call, a style.css, and a themes folder with Catppuccin variants. The project is MIT licensed.

### How do I install mechabar on my system?

The documented steps are to move any existing configuration with mv ~/.config/waybar{,.bak}, clone the repository into ~/.config/waybar, then run ~/.config/waybar/install, which the documentation says installs the dependencies and restarts Waybar. The dependency list itself is kept in the install file rather than in the documentation.

### Can I use a terminal other than kitty with mechabar?

Yes, but there is no global setting for it. The documentation instructs you to replace all invocations of kitty in the module files with your own terminal, editing each module definition that launches a script.

### How do I change the colour theme in mechabar?

Edit style.css and swap which file it imports from the themes directory. Four Catppuccin variants are shown, with Mocha as the default and Latte, Macchiato and Frappe available.

### Does mechabar publish releases I can install?

No. The repository has no GitHub releases, and the last push was on 2026-10-15. There is no tagged version to pin, so updates come from the main branch.

## Sources

- [Issues](https://github.com/sejjy/mechabar/issues)
- [License: MIT](https://github.com/sejjy/mechabar/blob/main/LICENSE)
- [README](https://github.com/sejjy/mechabar/blob/main/README.md)
- [sejjy/mechabar on GitHub](https://github.com/sejjy/mechabar)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sejjy-mechabar