PlaidBar

Your bank accounts, credit cards, and spending — always one click away in the macOS menu bar.

---

PlaidBar is an open-source macOS menu bar app that integrates with Plaid to display bank account balances, credit card utilization, recent transactions, and spending breakdowns — all from your status bar.

No cloud. No telemetry. All data stays local.

Why PlaidBar?

Personal finance data lives behind bank website logins. The closest thing to a menu bar finance app was Balance — commercial and now defunct. PlaidBar fills that gap as an open-source, privacy-first alternative.

• Glanceable — Net balance visible right in the menu bar
• Account Balances — All bank accounts and credit cards at a glance
• Recent Transactions — Searchable, filterable list grouped by day with category icons
• Transaction Detail — Tap any transaction for merchant, category, account, and status details
• Transaction Filtering — Filter by category, account, or date range with chip controls
• Recurring Detection — Automatic identification of subscriptions and recurring charges with monthly total
• Spending Breakdown — Donut chart, trend line, income vs expense views, and month-over-month comparison
• Credit Utilization — Progress bars with configurable warning thresholds and gauge
• Smart Notifications — Alerts for large transactions, low balances, and high credit utilization
• Balance History — Sparkline showing net balance trend over time
• Keyboard Shortcuts — Cmd+1-4 to switch tabs, Cmd+R to refresh, Cmd+N to add account
• Settings Persistence — Preferences saved across launches
• Launch at Login — Optional auto-start via macOS Login Items
• Auto-Updates — Sparkle integration for seamless updates
• Sandbox Mode — Try with demo data, no Plaid credentials needed
• Private — Everything stored locally on your Mac, period

Screenshots

Generate screenshots: ./Scripts/screenshots.sh (requires building in release mode)

Quick Start

1. Clone and build

git clone https://github.com/ftchvs/PlaidBar.git
cd PlaidBar
swift build

2. Run in sandbox mode (no credentials needed)

./Scripts/run.sh --sandbox

This starts both the local server and the menu bar app with Plaid's sandbox environment (demo bank data).

3. Click the PlaidBar icon in your menu bar

Select "Try with sandbox" → Add Account → complete the demo bank login in your browser → data appears instantly.

4. Use with real bank data (optional)

export PLAID_CLIENT_ID=your_client_id
export PLAID_SECRET=your_secret
./Scripts/run.sh

Get credentials free at dashboard.plaid.com. Sandbox works immediately; production requires Plaid approval.

Keyboard Shortcuts

Shortcut	Action
Cmd+1	Accounts tab
Cmd+2	Transactions tab
Cmd+3	Spending tab
Cmd+4	Credit tab
Cmd+R	Refresh balances
Cmd+N	Add account

Requirements

Requirement	Version
macOS	15.0 (Sequoia)+
Swift	6.0+
Xcode	16+ (or Swift toolchain)
Plaid account	Free for sandbox

Architecture

PlaidBar uses a two-process architecture — a SwiftUI menu bar app talks to a local companion server that proxies all Plaid API calls.

┌─────────────────────────────────────┐
│  PlaidBar.app (SwiftUI)             │
│  MenuBarExtra · Swift Charts        │
│  Accounts · Transactions · Spending │
└──────────────┬──────────────────────┘
               │ HTTP (localhost:8484)
┌──────────────▼──────────────────────┐
│  PlaidBarServer (Hummingbird 2)     │
│  Plaid API proxy · Fluent/SQLite    │
│  Token storage · OAuth callback     │
└──────────────┬──────────────────────┘
               │ HTTPS
┌──────────────▼──────────────────────┐
│  Plaid API                          │
│  /accounts · /transactions/sync     │
└─────────────────────────────────────┘

Why a companion server? Plaid requires that client_secret and access_token never exist in client code. The server:

1. Holds all secrets in a local SQLite database
2. Binds to 127.0.0.1 only — zero network exposure
3. Can be restarted independently of the UI
4. Opens the door for future CLI tools or iOS companion

Technology Stack

Layer	Technology	Why
Menu bar app	SwiftUI MenuBarExtra (.window)	Native macOS, modern API
Charts	Swift Charts	Built-in, no dependencies
Design system	Semantic tokens + 8pt grid	Consistent, maintainable
Local server	Hummingbird 2	Lightweight, SwiftNIO-based, same language as app
Database	SQLite via Fluent ORM	Migrations, queries, Hummingbird-native
Secrets (app)	macOS Keychain	OS-level secure storage
Auto-updates	Sparkle 2	Standard for open-source macOS apps
Launch at login	SMAppService	Native macOS Login Items API

Project Structure

PlaidBar/
├── Sources/
│   ├── PlaidBar/                    # macOS menu bar app
│   │   ├── App/                     # @main entry, AppState
│   │   ├── Theme/                   # Design tokens, typography
│   │   ├── Views/                   # SwiftUI views (4 tabs)
│   │   │   ├── AccountsView.swift   # Balance list by account type
│   │   │   ├── TransactionsView.swift # Searchable grouped list
│   │   │   ├── SpendingView.swift   # Donut/trend/bar charts
│   │   │   ├── CreditView.swift     # Utilization bars + gauge
│   │   │   ├── SetupView.swift      # Onboarding flow
│   │   │   └── Charts/             # Chart components
│   │   ├── Models/                  # Local cache models
│   │   ├── Services/                # HTTP client, refresh, launch
│   │   └── Settings/                # Preferences window
│   ├── PlaidBarServer/              # Local companion server
│   │   ├── Routes/                  # REST endpoints
│   │   ├── Plaid/                   # Plaid API client + models
│   │   ├── Storage/                 # Fluent models + migrations
│   │   └── Config/                  # Server configuration
│   └── PlaidBarCore/                # Shared library
│       ├── Models/                  # DTOs (Account, Transaction, etc.)
│       └── Utilities/               # Currency formatters, constants
├── Tests/                           # 61 tests across 3 suites
├── Scripts/                         # build.sh, run.sh, screenshots.sh
├── Assets/                          # README screenshots
├── DESIGN.md                        # Design system spec
├── PRD.md                           # Product requirements
├── .github/workflows/ci.yml        # GitHub Actions CI
├── Package.swift                    # SPM with 3 targets
└── LICENSE                          # MIT

Plaid API Usage

PlaidBar uses these Plaid endpoints:

Endpoint	Feature	Cost	Frequency
/link/token/create	Account setup	Free	On-demand
/item/public_token/exchange	Account setup	Free	Once per bank
/accounts/get	Cached balances	Free	Every 15 min
/accounts/balance/get	Real-time balances	Per-request	Manual refresh
/transactions/sync	Transactions	Per-item	Every 30 min

Rate limits are well within Plaid's allowances for personal use (~2-4 requests/hour/item).

Security

Concern	How PlaidBar handles it
Plaid secrets	Stored in server SQLite, never in app binary
Access tokens	Encrypted at rest, localhost-only server
Network exposure	Server binds to 127.0.0.1 only
App ↔ Server auth	Shared token generated at first run
Data at rest	macOS encrypted APFS volume
Distribution	Hardened runtime + notarized DMG (planned)

PlaidBar has no cloud backend, no analytics, no telemetry, and no tracking. Your financial data never leaves your machine.

Development

# Build all targets
swift build

# Build release
swift build -c release

# Run tests (61 tests)
swift test

# Run server standalone
swift run PlaidBarServer --sandbox

# Run both (server + app)
./Scripts/run.sh --sandbox

# Capture screenshots (demo mode)
./Scripts/screenshots.sh

# First-time setup helper
./Scripts/setup.sh

See CONTRIBUTING.md for code style, PR process, and architecture guidelines.

Server API Reference

The companion server exposes these localhost endpoints:

Method	Endpoint	Description
GET	/health	Health check
GET	/api/status	Server version, environment, item count
GET	/api/items	List connected bank items
POST	/api/link/create	Create Plaid Link token + URL
GET	/oauth/callback	Plaid OAuth redirect handler
GET	/api/accounts	List all accounts (cached)
GET	/api/accounts/balances	Real-time balances
DELETE	/api/accounts/:itemId	Remove a bank connection
GET	/api/transactions/sync	Incremental transaction sync

Roadmap

• Budget alerts per category
• Multi-currency support
• Investment account tracking (Plaid Investments)
• CSV/JSON export for tax/accounting
• Webhook support for real-time updates
• macOS notifications for large transactions
• Homebrew cask distribution
• Dark/light theme customization
• Teller as alternative provider (free tier)
• Recurring transaction detection

Inspiration

• RepoBar — GitHub stats in the macOS menu bar
• Balance — Commercial macOS finance app (defunct)
• Cashculator — Personal finance for Mac

License

MIT — Felipe Tavares Chaves