SketchyBar: a scriptable macOS status bar built around shell commands

What SketchyBar replaces and who ends up using it

macOS gives you one menu bar. You can reorder its icons with Command-drag, and you can hide them, but you cannot decide what information appears there, how it is laid out, or what happens when you click it. SketchyBar replaces that bar with its own, drawn as a separate window, and exposes every item on it as something you create and modify with commands.

The README states the intent plainly: the project aims to create a highly flexible, customizable, fast and powerful status bar replacement for people that like playing with shell scripts. That last clause is the honest part. SketchyBar is not a bar you configure in a preferences pane. It is a bar you program. The audience is people who already run a tiling window manager such as yabai, keep their configuration in a dotfiles repository, and are comfortable writing a shell script that polls a command and pushes a string into a bar item.

If that describes you, the payoff is that the bar can show anything a shell command can produce: battery state, a git branch, the current weather, a CPU graph, or the output of a script you wrote yourself. If it does not describe you, the same design is the reason to look elsewhere, because a bar with no items is an empty strip at the top of the screen.

The event system is the actual product

The README lists a dynamic animation system, a scripting and event system, interactive mouse support, display of macOS menu bar apps through aliases, arbitrary graphs, and on-demand popup menus. The feature that determines how you use everything else is the event system.

The stated design principle is that all elements of the bar can be added, removed and freely changed at any point in time. The configuration is therefore not static. A typical setup has a sketchybarrc file that runs at startup and defines the items, plus a directory of plugin scripts under ~/.config/sketchybar/plugins that each produce the content of one item. Those plugin scripts are ordinary shell scripts. They are registered against events, so when the event fires, the script runs, reads whatever it needs, and calls sketchybar again with a new value.

This is a different architecture from a status bar that owns a fixed set of widgets and reads system values on a timer. Here the bar is a display surface and a command parser; the logic lives outside the binary, in files you control. The practical consequence is that a slow plugin is your slow plugin. If a script shells out to a network call on every event, the bar waits on it.

The repository also ships a default sketchybarrc and a plugins directory at the top level, which the README points to as the way to become familiar with the syntax. Reading those files is the fastest route to understanding how items and events fit together, because the documentation describes commands and properties rather than complete configurations.

Installing SketchyBar and adding a first item

The README does not contain install commands. It says to refer to the installation guide in the documentation at felixkratz.github.io/SketchyBar/setup, and that is the only install path the README gives. Follow that page for the current method rather than copying a package manager command from a blog post, since the guide is the source the project maintains.

Once the program is set up, the README says the configuration lives in ~/.config/sketchybar/ and that this directory holds the sketchybarrc file and the plugin scripts. The same files exist in the repository root as sketchybarrc and plugins/, so you can read the shipped defaults before writing your own.

SketchyBar is driven from the command line, and the README suggests trying commands directly from the commandline to see which effect they have and how they alter the bar. The README does not print example commands, so the syntax to learn first is the one shown in the shipped sketchybarrc and in the plugin scripts under plugins/, which are the files the README tells you to become familiar with. Running those files' commands by hand, one at a time, is the workflow the README describes for learning what each one does to the bar.

The README also points to a Tips & Tricks section of the documentation and to a plugins discussion thread where users share functional items. If someone has already written the item you want, checking that thread before writing your own is the shorter path.

Where SketchyBar is the wrong tool

The same property that makes SketchyBar flexible makes it fragile in a specific way: nothing appears until you put it there. A fresh install with the default configuration is a starting point, not a finished bar. If you expect to install a program and immediately have a usable menu bar with the clock, battery and volume indicators you are used to, SketchyBar will look like a regression until you write the scripts.

There is a second constraint that follows from the architecture. The bar is only as reliable as the shell scripts feeding it. A plugin that fails silently, or a command whose output format changes after a system update, produces an item that is empty or stale. There is no settings window to open and no widget to re-enable. Debugging means reading your own scripts and running the sketchybar commands by hand to see what they do, which is the workflow the README recommends for learning the syntax in the first place.

The README also does not document rollback. It describes how to install and configure SketchyBar but says nothing about reverting to the stock macOS menu bar or uninstalling cleanly, so anyone who needs a guaranteed path back should treat that as an open question and check the documentation before installing.

Finally, SketchyBar draws its own bar. It is not an extension of the system menu bar, and the README's mention of aliases for displaying macOS menu bar apps is the mechanism for showing those apps inside SketchyBar rather than a claim that the native bar continues to work unchanged underneath.

How it compares to Bartender and to simple bar

The searches people run against this project include comparisons with Bartender and with simple bar, and the difference in approach is worth stating because the names suggest they compete on the same axis. They do not.

Bartender is a menu bar organizer. It works with the menu bar macOS already provides, hiding and revealing the icons that applications put there. SketchyBar does not organize the existing menu bar; it replaces it with a bar it draws itself and populates from commands. If your problem is that you have too many menu bar icons, an organizer addresses it directly. If your problem is that the menu bar cannot display the information you want at all, an organizer cannot help, because the information has to come from an application that puts an icon there.

simple bar, as the name suggests, is a lighter-weight bar. The relevant difference is the configuration model. SketchyBar's own description of itself is that it is for people that like playing with shell scripts, and its stated design principle is that every element can be added, removed and changed at any point in time. A simpler bar generally exposes a smaller, more fixed set of options. That is a real advantage for someone who wants a bar configured once and left alone, and it is the reason SketchyBar is not automatically the better choice for every user. The trade is capability for maintenance: SketchyBar asks you to own a script directory, and a simpler bar does not.

The README also names two related projects worth knowing about if you go the SketchyBar route. SbarLua provides a Lua API for SketchyBar, and sketchybar-app-font is a symbol font for it. Neither is required to use SketchyBar, but both exist because the shell-scripting model invites extensions.

Licence and the cost of keeping a configuration alive

SketchyBar is licensed under GPL-3.0, which the repository states in LICENSE.md and the README reflects in its licence badge. GPL-3.0 is a copyleft licence. For the typical user this changes nothing: you install the program and write scripts that call it. If you intend to redistribute a modified version of SketchyBar itself, or to ship it inside a product, the obligations are different and worth reading the licence text or asking someone qualified. This is not legal advice.

The upgrade cost is the more immediate concern for a user. The project is not archived, and the last push to the repository was on 2026-09-16. The most recent release listed is v2.24.0, titled Rendering System Overhaul, from 2026-06-04. A rendering overhaul is the kind of release that can change how the bar draws, and because your configuration is a set of scripts that issue commands, the thing to check after an upgrade is whether the commands and properties you rely on still behave the same way. The release notes are the place to look, and the README does not promise backwards compatibility for configuration commands.

In practice this means your sketchybarrc and your plugins directory are code you maintain. The effort is not large if you have a handful of items, but it is not zero, and it recurs whenever a release touches the rendering path or the command surface.

Editorial conclusion

Adopt SketchyBar if you already live in a terminal and want the menu bar to react to events rather than sit still, and if you accept that every item is something you write and maintain. Do not adopt it if you want a finished bar with a settings window, or if you are not willing to keep a script and its event subscriptions working across releases. Before committing, verify that the install path on felixkratz.github.io/SketchyBar/setup matches your macOS version and chip, that ~/.config/sketchybar/ is where your sketchybarrc and plugins will live, and that the properties you rely on are documented for the current release.

Frequently asked questions

Official sources

1. FelixKratz/SketchyBar on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases