pforret/bashbar

A collection of SwiftBar plugins written in Bash and the toolkit to make new ones

SwiftBar lets you add custom items to the macOS menu bar using simple scripts. This repo provides a shared framework (core.sh) and several ready-to-use plugins.

Plugins

Plugin	Refresh	Description
template.1h.sh	1 hour	Disk usage - use as starting point for new plugins
memory.5m.sh	5 min	RAM usage with detailed breakdown
vitals.5m.sh	5 min	Cycles between disk, RAM, CPU, network and battery

Install / Uninstall

Each plugin can install itself into your SwiftBar Plugin Folder via a symlink:

./vitals.5m.sh install     # symlink into SwiftBar Plugin Folder
./vitals.5m.sh uninstall   # remove the symlink
./vitals.5m.sh help        # show usage

The Plugin Folder is detected automatically from SwiftBar's preferences.

Creating a new plugin

1. Copy the template:

   cp template.1h.sh myplugin.5m.sh
   chmod +x myplugin.5m.sh

2. Edit myplugin.5m.sh:
   • Update the filename: {name}.{refresh}.sh (e.g. weather.10m.sh)
   • Update the metadata block (xbar.title, xbar.desc, etc.)
   • Replace the plugin_output() function with your own logic
3. Install it:

   ./myplugin.5m.sh install

Architecture

core.sh            # Shared framework (env loading, output helpers, install/uninstall)
template.1h.sh     # Template plugin - copy this to start a new plugin
memory.5m.sh       # RAM usage plugin
vitals.5m.sh       # System vitals plugin

core.sh

Provides the SwiftBar output API, env loading, and plugin management. Each plugin sources it with:

SCRIPT_DIR="$(cd "$(dirname "$(readlink "$0" || echo "$0")")" && pwd)"
source "${SCRIPT_DIR}/core.sh"

This resolves symlinks, so plugins work correctly when installed via ./plugin.sh install.

Output functions

Function	Purpose
metric "icon" "header" "menu text" "color"	Cycling menu bar item + dropdown entry (icon shared)
menu_line "text"	Dropdown-only item with separator
detail_line "text"	Indented sub-item in dropdown

Output is buffered so that all header lines appear before dropdown content, regardless of call order. This lets you group data collection and output per metric. A Refresh button and flush are appended automatically by swiftbar_run.

Helper functions

Function	Purpose
color_for_pct <pct> [warn] [crit] [default]	Returns color based on percentage thresholds

color_for_pct defaults: warn=75 (orange), crit=90 (red), default=white. Override thresholds per metric, e.g. color_for_pct 80 50 80 green.

Environment loading

On startup, core.sh automatically loads .env files in this order (later files override earlier ones):

1. ${SCRIPT_DIR}/.env — shared secrets for all plugins in the repo
2. ${SCRIPT_DIR}/.${prefix}.env — plugin-specific (e.g. .check_api.env)
3. ${PLUGIN_DIR}/.env — shared secrets in SwiftBar Plugin Folder
4. ${PLUGIN_DIR}/.${prefix}.env — plugin-specific in SwiftBar Plugin Folder

The prefix is the plugin name without refresh interval and extension (e.g. check_api from check_api.1h.sh). This lets you store API keys or other secrets outside the repo.

Management

Function	Purpose
swiftbar_run "$@"	Dispatch: install, uninstall, help, or run plugin_output()

Plugin structure

A minimal plugin looks like this:

#!/usr/bin/env bash
# <xbar.title>My Plugin</xbar.title>
# <xbar.desc>Does something useful</xbar.desc>

SCRIPT_DIR="$(cd "$(dirname "$(readlink "$0" || echo "$0")")" && pwd)"
source "${SCRIPT_DIR}/core.sh"

plugin_output() {
  local value=42
  metric "🔧" "${value}" "My metric: ${value}" "$(color_for_pct "${value}")"
  detail_line "Some detail here"
}

swiftbar_run "$@"

Requirements

• macOS
• SwiftBar
• Bash