A lightweight macOS menu bar client for Umami. Keep multiple websites in one popover, track traffic changes, and open a site's details without leaving your workflow.
Built with AppKit, native drawing, URLSession, and macOS Keychain. The app does not embed WebKit or require a local web server. The HTML prototype is a separate design reference.
Contents
Features
- Multiple websites: visitor totals, compact session charts, and traffic quality metrics in one list.
- Four time ranges: today (compared with yesterday up to the same time), last 24 hours, last 7 days, and last month.
- Period comparisons: visitor changes against the preceding interval of equal length, with a separate “New” state when the previous count is zero.
- Website details: click a website name or chart for a larger session chart, top pages, and traffic sources.
- Native interactions: chart hover values, keyboard navigation within charts, and return to the previous overview scroll position.
- Automatic appearance: light and dark themes follow macOS, with glass surfaces and warm orange charts.
- Native menu bar sizing: a system square for icon-only mode and content-based width for numbers, with monospaced digits, compact large numbers, and exact counts in the tooltip.
- Refresh feedback: a spinner while loading, a timestamp with seconds, and periodic refresh while the popover is open.
- Traffic alerts: optional notifications when a site's traffic drops to zero (often a broken tracking script) or spikes; clicking one opens that site's details.
- Secure credentials: API keys are stored in Keychain; website selections and preferences are stored locally.
The documentation is available in English and Chinese. The current app interface is in Chinese; an in-app language switch is not implemented.
Screenshots
| Mode | Overview | Website details |
|---|
| Dark | | |
| Light | | |
Sample data.
Requirements
| Component | Requirement |
|---|
| Intel Mac | Deployment target: macOS 10.15 Catalina or later |
| Apple Silicon Mac | Deployment target: macOS 11 or later |
| Build tools | Xcode with a macOS SDK and Swift 5.9 or later |
| Umami | A deployment supporting Bearer API key authentication |
The app uses Sparkle 2 for automatic update checks and manual checks in Settings → General → Check for Updates. In-app updates use signed, notarized tagged releases; CI builds are ad-hoc signed and are not updateable. Sparkle is the sole third-party Swift package dependency.
Homebrew installation
After the first release is published and its Cask update PR is merged:
brew tap helson-lin/umamibar https://github.com/helson-lin/umamibar
brew install --cask helson-lin/umamibar/umamibar
Upgrade with brew update, then brew upgrade --cask helson-lin/umamibar/umamibar. Homebrew's own legacy macOS support is separate from the app's deployment target. Older Macs can use the release ZIP directly.
Download the universal DMG from Releases, open it, and drag UmamiBar.app to Applications. Eject the disk image, then launch from Applications. Signed release builds support automatic Sparkle checks and manual checks in Settings → General → Check for Updates. Homebrew users update with the command above.
CI tests and packages the universal app on Intel and Apple Silicon for every branch push, pull request, and manual run. No tag is needed: open Actions → CI, select a successful run, and download either UmamiBar-macos-15 or UmamiBar-macos-15-intel from the summary (both contain a universal app; retained for 14 days; GitHub sign-in required). Extract the artifact, unzip the inner UmamiBar-<version>-universal.zip, and move UmamiBar.app to Applications. To package manually, select Run workflow and the desired branch.
Push a vX.Y.Z tag matching VERSION to publish the DMG, ZIP, SHA-256 checksums, signed Sparkle appcast, and generated Cask, then open a Cask update PR. See RELEASING.md for setup and release instructions.
Tagged releases require Developer ID signing, Apple notarization, and the SPARKLE_EDDSA_PRIVATE_KEY Actions secret; see release setup. Ordinary CI builds remain ad-hoc signed and unnotarized. Existing releases are unchanged.
Build and run
From the repository root:
./scripts/build-app.sh
open dist/UmamiBar.app
The application bundle is generated at dist/UmamiBar.app. Copy it to your Applications folder if desired. It runs in the menu bar without a Dock icon.
For a local development build using only the host architecture:
./scripts/build-app.sh native
The native-only build uses the toolchain's default deployment target. Use the default universal build when checking the explicit legacy deployment targets.
Builds are ad-hoc signed for local development. They are not Developer ID signed or notarized. GitHub Actions can publish release ZIPs; application self-updating is not implemented.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
