SwiftBar: Script-Driven Menu Bar Items on macOS

The problem SwiftBar solves for macOS users

macOS gives you a menu bar and no supported way to put your own text in it. Getting a build status, a disk figure, or the current branch of a repository to sit next to the clock normally means writing a full application bundle in Swift or Objective-C. SwiftBar removes that step. You write an executable script in any language, drop it into a folder, and its standard output becomes a menu bar item with a dropdown menu underneath.

The audience is narrow and specific: people who already live in a shell. If your useful information is already reachable from a command, SwiftBar is a thin display layer over it. If your information lives behind an API that needs OAuth, pagination and retry logic, the script you write will be doing all the real work and SwiftBar will only be drawing the result. That is not a criticism of the design, but it does mean the tool's value scales with how much of your work is already scriptable.

The README states the contract plainly: write a shell script, add it to SwiftBar, and there is no third step. It is MIT licensed and runs on macOS Monterey (12) and later.

How the plugin folder and refresh interval work

Everything starts with the Plugin Folder, which SwiftBar asks you to set on first launch. Every file in that folder is imported as a plugin, with three exceptions the README calls out: hidden folders are ignored, nested folders are traversed including through symlinks, and a `.swiftbarignore` file can exclude files from being imported. That last detail matters more than it looks. Without an ignore file, a stray README or a backup file in the same directory becomes a plugin and gets executed.

Refresh is encoded in the filename, not in a config file. The format is `{name}.{time}.{ext}`, where the time segment is optional and combines a number with a duration modifier: `ms`, `s`, `m`, `h` or `d`. The README's example is `date.1m.sh`, which refreshes every minute. A file named without a time segment is not refreshed on a schedule at all.

Ordering is manual. Plugins initially appear in no pre-determined order, and you reorder them by holding Cmd and dragging. The README notes this can sometimes work on non-SwiftBar menu bar icons too. Position is remembered unless you rename the plugin file, in which case you position it again. Renaming a file to change its refresh interval therefore costs you its place in the bar, which is a small but real friction point.

The stdout format: header, body and parameters

A plugin is an executable script that SwiftBar makes executable if needed and then runs. Output on stdout is parsed; errors are expected on stderr. The parser splits the output into two blocks. Everything before the first `---` is the header and controls the menu bar itself. Everything after is the body and becomes the dropdown. Each subsequent `---` is a menu separator.

The simplest possible plugin is one line of output, which the README gives as:

echo "This is Menu Title"

Multiple header lines cycle through the menu bar and also appear in the dropdown. Each line, in both header and body, follows the shape `<Item Title> | [param = ...]`, with a pipe separating the title from parameters and spaces separating multiple parameters. The parameter table in the README covers text formatting (`color`, `font`, `size`, `md` for markdown, `length` to trim with the full title in a tooltip, `trim`), symbol handling (`symbolize` for SF Symbols, `emojize` for GitHub-style shortcodes, `ansi` for ANSI color codes) and visuals (`dropdown`, `alternate`, `image`).

Two constraints in that table are worth reading twice. `ansi` conflicts with `symbolize`, and setting `emojize` to true requires `symbolize=false`. The README also notes `symbolize` is always false on Catalina. These are the kind of interactions that produce a plugin that looks fine on one machine and wrong on another.

Installing SwiftBar with Homebrew and running a first plugin

The README gives two routes. You can download from GitHub Releases, or install with Homebrew:

brew install swiftbar

After launching, SwiftBar asks you to set the Plugin Folder. Pick a directory you control, and keep in mind that hidden folders are ignored, so a folder whose name begins with a dot will not work. Then create a script whose filename carries a refresh interval. The README's own example filename is `date.1m.sh`, which refreshes every minute, and it shows a minimal plugin body as a single echo of the menu title. Put that in a file with the interval in its name inside the Plugin Folder, and SwiftBar will import it and run it.

The README also documents building from source: clone the repository, open `SwiftBar/SwiftBar.xcodeproj`, and press play. There is a bundled Plugin Repository reachable from the Swiftbar menu under Get Plugins, which is the fastest way to see working examples before writing your own. SwiftBar's plugin API is adopted from BitBar, so existing BitBar plugins can run unmodified.

Where SwiftBar is the wrong tool

The design assumes your script is fast, self-contained and safe to run repeatedly. Nothing in the README describes a timeout, a concurrency guard, or a sandbox. A plugin that shells out to a network call on a `1s` interval runs that call every second, and if the call takes longer than a second you have overlapping executions with no documented coordination between them. The refresh interval is a scheduling hint in a filename, not a rate limiter.

Error handling is similarly thin. Script errors go to stderr, and the README does not document what the menu bar shows when a script exits non-zero or produces no output. If your plugin depends on a credential that expires, you should design the failure state into the script's output rather than assume SwiftBar will surface it.

The plugin folder model is also a blunt instrument. Every non-hidden file is treated as a plugin and executed, which means a folder shared with other tooling needs a `.swiftbarignore` to stay clean. And if you want a menu bar item that is configured through a preferences window rather than a file, SwiftBar is the wrong shape entirely: the file is the configuration.

SwiftBar compared with xbar

The obvious alternative is xbar, and the relationship is closer than a typical competitor comparison. SwiftBar's README states that its plugin API is adopted from BitBar/xbar, which means SwiftBar can run any existing BitBar/xbar plugin. The two projects share a plugin format, so the practical difference is not what you can display but how the host application behaves.

That shared format is the useful part. If you have a directory of xbar plugins, the migration cost to SwiftBar is close to zero, and the reverse is also true. The README points at the BitBar plugin repository as a source of plugins, and SwiftBar ships its own Plugin Repository behind the Get Plugins menu item. Choosing between them comes down to the host application rather than the plugin contract, and the README does not attempt a feature-by-feature comparison, so treat any such comparison you read elsewhere as coming from a source other than this repository.

If your actual requirement is a cross-platform tray icon, neither project is the answer. Both are macOS-only, and SwiftBar's stated floor is macOS Monterey (12) and later.

Maintenance, licensing and upgrade cost

SwiftBar is MIT licensed, which is permissive and places few obligations on how you redistribute or modify it. That applies to the application. Plugins you write or pull from the plugin repository carry their own licensing, and the README does not make any blanket statement about the licence of repository contents, so check individual plugins if you plan to redistribute them. This is a description of the licence text, not legal advice.

The repository is not archived, and the last push was on 2026-08-15. The most recent releases listed are three betas of 2.1.2, dated 2026-08-12, 2026-08-14 and 2026-08-15. Anyone installing through Homebrew should be aware that the release channel shown here is beta-tagged rather than a stable 2.1.2, and the README does not describe a separate stable channel or a rollback procedure.

Upgrade cost is mostly on your side. Because the plugin contract is a text format on stdout, upgrading the host application does not require rewriting plugins, and the format's lineage from BitBar means it has been stable across two projects. The real maintenance burden is the scripts: anything that calls an external service will break when that service changes, and SwiftBar will not tell you why.

Editorial conclusion

Adopt SwiftBar if you already have shell scripts or command-line tools whose output you want visible without opening a terminal, and if you are comfortable owning the scripts yourself. Skip it if you need a GUI plugin builder or a plugin format with a formal schema and validation step. Before committing, verify three things on your own machine: that your scripts emit the header and body format described in the README, that your Plugin Folder is not a hidden directory (hidden folders are ignored), and that the refresh interval in the filename is short enough for the data but not so short that the script overlaps itself. If your plugin depends on a network call or a slow command, test with a long interval first and tighten it only after you have watched the menu bar for a while.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. swiftbar/SwiftBar on GitHub