EasyBar

EasyBar is a lightweight, scriptable macOS status bar built with SwiftUI and Lua.

It combines native built-in widgets with custom Lua widgets and is designed for an AeroSpace-based macOS workflow.

Features

• Native macOS bar window built with SwiftUI
• Built-in widgets plus scriptable Lua widgets
• File-based themes with bundled and custom TOML palettes
• AeroSpace integration for spaces, focused app state, and layout mode state
• Event-driven updates and interactive popups
• Calendar and network helper agents
• Homebrew install and service workflow
• Config-driven logging and troubleshooting support
• Lightweight runtime metrics

Installation

brew tap gi8lino/tap
brew install gi8lino/tap/easybar

Start EasyBar and its helper agents:

brew services start gi8lino/tap/easybar-calendar-agent
brew services start gi8lino/tap/easybar-network-agent
brew services start gi8lino/tap/easybar

Documentation

Full documentation is available here: https://gi8lino.github.io/easybar/

Start with:

• Installation
• Configuration
• Themes
• AeroSpace Integration
• Lua Widgets
• Runtime Control
• Troubleshooting
• Architecture

Configuration

EasyBar reads its runtime config from:

~/.config/easybar/config.toml

You can override it with:

EASYBAR_CONFIG_PATH=/path/to/config.toml

The repository includes:

• config.defaults.toml
• config.minimal.toml

Themes are selected in config.toml:

[theme]
name = "default"
themes_dir = "~/.config/easybar/themes"

EasyBar first looks for a custom theme in themes_dir, then falls back to bundled themes.

Developing

Quickstart for contributors:

make test
make stop
make run-debug

Useful build and runtime commands:

• make test runs the full Swift test suite.
• make build builds the local app, agents, and CLI artifacts.
• make run-debug starts EasyBar with verbose logging for local debugging.
• make stop stops the running EasyBar app and helper agents cleanly.
• make validate-config CONFIG=/path/to/config.toml builds the CLI and asks EasyBar to dry-run config validation without reloading the bar.

Generated artifacts

Regenerate checked-in generated files before committing changes to theme tokens, event catalog data, Lua API stubs, or generated Lua reference docs:

make generate

Regenerate only generated documentation when the runtime or Lua API docs changed:

make generate-docs

Before opening a pull request, verify that generated files are current:

make check-generated

Helper scripts

Reusable automation lives under scripts/ and is grouped by purpose:

• scripts/ci/ contains CI-only wrappers such as dependency setup and long-running Swift test logging.
• scripts/release/ contains release automation such as Homebrew formula rendering and tap commits.
• Existing generator scripts remain the source of truth for generated Swift, Lua, and documentation artifacts and are still orchestrated through the Makefile.

Keep local developer entrypoints in the Makefile where possible, and move only reusable implementation details into scripts. That keeps commands like make generate, make build-docs, and make package stable while avoiding large shell blocks in workflows.

Helpful entry points in the codebase:

• Sources/EasyBarApp/App contains the main app shell and startup wiring.
• Sources/EasyBarApp/Runtime contains config reload, file watching, and socket orchestration.
• Sources/EasyBarApp/Widgets contains native widgets, Lua runtime integration, and rendered widget state.
• Sources/EasyBarCalendarAgent and Sources/EasyBarNetworkAgent contain the helper agent apps.
• Sources/EasyBarShared contains shared runtime, logging, socket, and protocol code used across targets.

If you want the architectural map before editing code, start with the docs sections for Architecture, Agents, and Lua Runtime in the project docs.

Screenshots

Calendar

Upcoming

CPU

Front app

Wi-Fi

Context menu

License

This project is licensed under the Apache 2.0 License. See LICENSE for details.