This bar project aims to create a highly flexible, customizable and fast statusbar for users that like playing around with shell scripts and want to make their statusbar show exactly the information they need for their workflow.
The configuration of the bar takes place in a confiuration file where almost everything can be configured. Bascially, the bar itself is a rectangle that can hold arbitrarily many items and components, which can be configured to do awesome stuff. An item will occupy a space in the bar and can be equipped to show an icon and a label. The icon and label can be changed through scripts that can be attached to the item. It is also possible to subscribe and item to certain events for their script execution action, which makes very powerful items possible. Additionally, an item can be assigned a click_script, which executes on a mouse click. Furthermore, an item can be assigned to mission control spaces or displays, such that they only show on a certain space or display, which makes multi-desktop configuration of the bar possible and opens the possibility to create individualized bar configuration on a per display and per space level. These simple ingredients make items almost endlessly customizable and can be used to display arbitrary information and perform useful actions. For some examples see my sketchybarrc and the plugins folder.
Some special features can not be accomplished with a simple item, this is where the components come into play. They basically are items with extra steps. They contain all the properties a regular item does, but they can do specialized tasks a simple item can not. For example, there is a graph component, which can be used to display graphs in the bar.
For more details on how the configuration works, see the Configuration section below.
This is an example setup (see more example setups here): where I have my spaces and a Github indicator on the left. Not shown is the high memory warning which shows the process that is using high system memory on demand. In the center I have a spotify indicator (only when music is playing) and on the right I have (not shown) a high cpu process indicator, as well as a cpu graph, a new mail counter and the current date.
brew tap FelixKratz/formulae brew install sketchybar
Do not forget to copy the example configuration files to your home directory:
mkdir ~/.config/sketchybar cp /usr/local/opt/sketchybar/share/sketchybar/examples/sketchybarrc ~/.config/sketchybar/sketchybarrc mkdir ~/.config/sketchybar/plugins cp -r /usr/local/opt/sketchybar/share/sketchybar/examples/plugins/ ~/.config/sketchybar/plugins chmod +x ~/.config/sketchybar/plugins/*
and run the bar via
brew services start sketchybar
If you want to use your own plugins, make sure that they are referenced in the rc with the correct path and that they are made executable via
chmod +x name/of/plugin.sh
Have a look at the discussion about plugins and share your own if you want to. You should of course vet the code from all plugins before executing them to make sure they are not harming your computer.
If you have problems with missing fonts you might need to install the Hack Nerd Font:
brew tap homebrew/cask-fonts brew install --cask font-hack-nerd-font
For an example configuration see the supplied default sketchybarrc.
sketchybar -m --bar <setting>=<value> ... <setting>=<value>
where the settings currently are:
Items are the main building blocks of sketchybar and can be configured in a number of ways. Items have the following basic structure:
sketchybar -m --add item <name> <position>
where the name should not contain whitespaces, it can be used to further configure the item, which is covered later. The position is the placement in the bar and can be either left, right or center. The items will appear in the bar in the ordered in which they are added.
sketchybar -m --set <name> <property>=<value> ... <property>=<value>
where the name is used to target the item with this name.
A list of properties available to the set command is listed below (components might have additional properties, see the respective component section for them):
It is possible to change the defaults at every point in the configuration. All item created after changing the defaults will inherit these properties from the default item.
sketchybar -m --default <property>=<value> ... <property>=<value>
this works for all item properties.
It is also possible to reset the defaults via the command
sketchybar -m --default reset
Components are essentially items, but with special properties. Currently there are the components (more details in the corresponding sections below):
sketchybar -m --add graph <name> <position> <width in points>
Additional graph properties:
Push data points into the graph via:
sketchybar -m --push <name> <data point>
sketchybar -m --add space <name> <position>
The space component overrides the definition of the following properties and they must be set to correctly associate a mission control space with this item:
$SELECTED $SID $DID
where $SELECTED has the value true if the associated space is selected and false if the selected space is not selected, while $SID holds the space id and $DID the display id.
By default the space component invokes the following script:
if [ "$SELECTED" = "true" ]; then sketchybar -m --set $NAME icon.highlight=on else sketchybar -m --set $NAME icon.highlight=off fi
which you can freely configure to your liking by supplying a different script to the space component:
sketchybar -m --set <name> script=<path to script>
For performance reasons the space script is only run on change.
It is possible to bracket together items via the command (see this discussion for an example):
sketchybar -m --add bracket <name> <first item name> ... <n-th item name>
The first item must always be the one listed earliest in the config. It is now possible to set properties for the bracket, just as for any item or component. Brackets currently only support all background features. E.g., if I wanted a colored background around all my space components (which are named code, writing, reading and entertainment) I would set it up like this:
sketchybar -m --add bracket primary_spaces code \ writing \ reading \ entertainment \ \ --set primary_spaces background.color=0xffffffff \ background.corner_radius=4 \ background.height=20
this draws a white background below all my space components. I plan to expand the capability of item brackets significantly in the future.
It is possible to create an alias for default menu bar items (such as MeetingBar, etc.) in sketchybar. The default menu bar can be set to autohide and this should still work.
I highly recommend setting a wallpaper on all spaces that makes the default menu bar items appear in either the light or the dark theme consitently.
It is now possible to create an alias of a default menu bar item with the following syntax:
sketchybar -m --add alias <application_name> <position>
this operation requires screen capture permissions, which should be granted in the system preferences. This will put the default item into sketchybar. Aliases currently are not clickable but can be modified with all the options available for simple items.
The command can be overloaded by providing a window_owner and a window_name
sketchybar -m --add alias <window_owner>,<window_name> <position>
this way the default system items can also be slurped into sketchybar, e.g.:
Owner: "Control Center", Name: Bluetooth
Owner: "Control Center", Name: WiFi
Or the individual widgets of Stats:
Owner: Stats Name: CPU_Mini
All further default menu items currently available on your system can be found via the command:
sketchybar -m --query default_menu_items
This pushes the data point into the graph with name name.
It is possible to batch commands together into a single call to sketchybar, this can be helpful to keep the configuration file a bit cleaner and also to reduce startup times. Assume 5 individual configuration calls to sketchybar:
sketchybar -m --bar position=top sketchybar -m --bar margin=5 sketchybar -m --add item demo left sketchybar -m --set demo label=Hello sketchybar -m --subscribe demo system_woke
after each configuration command the bar is redrawn (if needed), thus it is more perfomant to append these calls into a single command like so:
sketchybar -m --bar position=top \ margin=5 \ --add item demo left \ --set demo label=Hello \ --subscribe demo system_woke
The backslash at the end of the first 4 lines is the default bash way to join lines together and should not be followed by a whitespace.
Any item can subscribe to arbitrary events, when the event happens, all items subscribed to the event will execute their script. This can be used to create more reactive and performant items which react to events rather than polling for a change.
sketchybar -m --subscribe <name> <event> ... <event>
where the events are:
When an item is subscribed to these events the script is run and it gets passed the $SENDER variable, which holds exactly the above names, to distinguish between the different events. It is thus possible to have a script that reacts to each event differently e.g. via a switch for the $SENDER variable in the script. I will soon create an example an link it here.
Alternatively a fixed update_freq can be --set, such that the event is routinely run to poll for change.
When an item invokes a script, the script has access to some environment variables, such as:
Where $NAME is the name of the item that has invoked the script and $SENDER is the reason why the script is executed.
This allows to define events which are triggered by a different application (see Trigger custom events). Items can also subscribe to these events for their script execution.
sketchybar -m --add event <name> [optional: <NSDistributedNotificationName>]
Optional: You can subscribe to the notifications sent to the NSDistributedNotificationCenter e.g. the notification Spotify sends on track change: "com.spotify.client.PlaybackStateChanged" example, or the notification sent by the system when a bluetooth device connected, or disconnected: com.apple.bluetooth.state (example) to create more responsive items.
This triggers a custom event that has been added before
sketchybar -m --trigger <event>
This could be used to link the powerful event system of yabai to sketchybar by triggering the custom action via a yabai event.
sketchybar -m --update
SketchyBar can be queried for information about a number of things.
Information about the bar can be queried via:
sketchybar -m --query bar
The output is a json structure containing relevant information about the configuration settings of the bar.
Information about an item can be queried via:
sketchybar -m --query item <name>
The output is a json structure containing relevant information about the configuration of the item.
Information about the current defaults.
sketchybar -m --query defaults
Currently only on HEAD. It is possible to reorder items by invoking
sketchybar -m --reorder <name> ... <name>
where a new order can be supplied for arbitrary items. Only the specified items get reordered, by swapping them around, everything else stays the same. E.g. if you want to swap two items simply call
sketchybar -m --reorder <item 1> <item 2>
Currently only on HEAD.
It is possible to move items and order them next to a reference item.
sketchybar -m --move <name> before <reference name>
sketchybar -m --move <name> after <reference name>
Currently only on HEAD. It is possible to clone another item instead of adding a completely blank item
sketchybar -m --clone <name> <parent name>
the new item will inherit all properties of the parent item.
Currently only on HEAD. It is possible to rename any item. The new name should obviously not be in use by another item:
sketchybar -m --rename <old name> <new name>
Currently only on HEAD. It is possible to remove any item by invoking, the item will be completely destroyed and removed from brackets
sketchybar -m --remove <name>
SketchyBar can be configured to have a very small performance footprint. In the following I will highlight some optimizations that can be used to reduce the footprint further.