matryer/xbar-plugins: What the Plugin Repository Actually Gives You

What xbar-plugins solves, and for whom

xbar is a macOS menu bar host. It runs scripts on a schedule and renders their stdout as menu bar items. The host gives you the runtime; it gives you nothing to run. matryer/xbar-plugins is the answer to that second half. It is a categorised collection of scripts, programs and command-line tools that add functionality to xbar, in the README's words. The audience is narrow and specific: a macOS user who already has xbar installed and wants a menu bar readout for something, without writing the polling loop, the output formatting and the click handling from scratch.

The repository is not a library you import. The top level is a set of topic folders (AWS, Cloud, Cryptocurrency, Dev, Finance, Music, Network, System, Time, Tools, Weather, Web, and others), plus an Enabled folder, a CONTRIBUTING.md and the README. Shell is the primary language, which tells you what kind of artefact lives here: small executables, not modules. That shape is the point. A plugin is a file you can read end to end in a minute before you let it run on your machine.

How a plugin reaches the menu bar

The mechanism is a contract between xbar and an executable. A plugin is a script or program placed in the xbar plugins folder. xbar executes it and treats its standard output as the menu bar content. The README's usage section is the whole data flow in three steps: drop the plugin into your xbar plugins folder, make sure it is executable, then choose Refresh all from the xbar menus.

That is worth pausing on, because it defines the security model. A plugin is arbitrary code with your user's privileges, executed on a refresh interval you did not necessarily choose. There is no sandbox described in the README, no manifest, no permission declaration. The repository's defence is visibility: the source is right there in a category folder, and Shell scripts are readable. If you install a plugin you have not opened, you are trusting the author completely. The README does not claim otherwise.

The Enabled folder deserves a note. The README suggests using it if you have the repository checked out, which implies a workflow where the repository itself is the plugins folder and Enabled is the subset you have switched on. That is a reasonable way to keep the full catalogue around without running all of it, but it also means a git pull can change what is enabled if you have not been deliberate about which files live there.

Installing a plugin and getting a first readout

There is no installer. The README's instructions assume you already have xbar and a plugins folder. The README's own usage section says to make the plugin executable, and gives this command form:

chmod +x plugin.sh

After that, the README says to choose Refresh all from the xbar menus. What you should see is the plugin's output appear in the menu bar. If nothing appears, the usual causes are a non-executable file or a script that failed silently, and the README does not describe a debug log, so you are left running the script directly in Terminal to see its output.

If you have the repository checked out locally and want to work from the Enabled folder as the README suggests, the same command applies to a file under that folder. The practical first move is to run the script by hand before enabling it. Running it in Terminal shows you both the output xbar will render and any error text xbar would swallow. The README does not document this step, but it follows from the fact that a plugin is just an executable.

The maintenance question the repository does not answer

The repository itself was last pushed on 2026-09-17, and it is not archived, so the collection as a whole is being touched. That says nothing about the individual plugin you want. A directory with this many categories accumulates scripts of very different ages, and the README offers no per-plugin status, no deprecation marker, no compatibility note.

The README does point at a partial substitute: report issues by finding the plugin on xbarapp.com and clicking Open issue, and if possible the author will be tagged, which the README says greatly increases your chances of getting the issue looked at quickly. Read that carefully. It is an admission that issue triage depends on whether a volunteer author is still reachable. There is no release process in the repository, no versioned plugin artefacts, and no changelog described in the README. Your upgrade path is whatever git pull gives you, and your rollback path is not documented at all.

For a personal menu bar widget that is an acceptable trade. For anything you would put on a colleague's machine and be asked to support, it is not.

Where xbar-plugins is the wrong tool

If you need a menu bar item that is stable across macOS updates, backed by someone accountable, and configurable without editing a script, this repository is the wrong shape. Plugins are contributed scripts, not products. The README's contribution guide is aimed at people adding plugins, not at people demanding service levels.

A second failure mode is scope. If your need is a single readout, say a build status or a disk figure, browsing categories is slower than writing twenty lines of Shell yourself, and you avoid inheriting someone else's dependencies and output quirks. The repository is most valuable when you want breadth quickly: many small readouts across AWS, Cloud, Finance, Weather and System, and you are willing to audit each one.

A third case is non-macOS. xbar is a macOS menu bar application. Nothing in the repository layout suggests a Linux or Windows host, and the README's usage instructions are written around the xbar menus.

SwiftBar and the difference in approach

SwiftBar is the obvious alternative to name, and the difference is architectural rather than cosmetic. Both host scripts in the macOS menu bar. The distinction that matters for this repository is where the plugin catalogue lives. matryer/xbar-plugins is a central, curated-by-category repository that you clone or copy from, with the xbarapp.com site as the browsing and issue-reporting front end. SwiftBar's model centres on the host application and its own plugin directory, so a plugin you find for it is typically distributed by its author rather than through one shared catalogue with a single contribution guide.

That changes your workflow. With xbar-plugins you get one place to search, one CONTRIBUTING.md, and one issue route via xbarapp.com. You also inherit the catalogue's uneven maintenance. With a host-centric model you get less centralisation and, in exchange, plugins that are usually tied to a single author's own distribution. Neither is strictly better; the central catalogue saves discovery time and costs you a uniform maintenance guarantee you were never going to get anyway.

Licence and the cost of keeping plugins current

The repository's licence is not stated in the README or the top-level file listing. That is a real gap, not a formality: a plugin is code you execute with your own privileges, and without a licence you have no stated grant to redistribute or modify it. If you plan to fork a plugin, vendor it into an internal repository, or ship it to colleagues, resolve the licence question with the individual plugin author before you do. Nothing here is legal advice, and the absence of a licence file at the top level is exactly the kind of thing that turns into a problem only after you have already copied the code.

Upgrade cost is low in the mechanical sense and unpredictable in the practical sense. No releases are listed for this repository, so there is no version to pin. Updating means pulling the repository and seeing what changed in the scripts you enabled. Because plugins are independent executables, an update to one cannot break another, which limits blast radius. It also means no one is checking that your combination still works together. Budget for reading diffs on the handful of plugins you actually enable, not for a dependency upgrade process.

Editorial conclusion

Adopt matryer/xbar-plugins if you already run xbar on macOS and want a script to copy rather than write. Do not adopt it if you expect a package manager, versioning or a support contract: the README's whole install procedure is placing a file and running chmod +x. Before relying on any single plugin, open its source in the category folder, confirm what command it shells out to, and check whether the author is tagged on the xbarapp.com issue page, because the repository itself carries no per-plugin maintenance metadata.

Frequently asked questions

Official sources

1. Issues
2. matryer/xbar-plugins on GitHub
3. Project website
4. README