Expenses

Monthly expense tracker for the Omarchy bar, with per-category budget limits and a green/yellow/red traffic light on the bar number. Manual entry, month browsing (◀ ▶), income tracking, and sync to your own ezBookkeeping server (optional).

Install

omarchy plugin add https://github.com/Wardad52/expenses.git --enable

Or clone manually into ~/.config/omarchy/plugins/io.github.wardad52.expenses/ and enable:

omarchy plugin enable io.github.wardad52.expenses
omarchy-shell shell rescanPlugins

Usage

• Click the $ widget: shows the current-month total · count. The number is green by default; it turns yellow when a category is within $25 of its monthly budget limit, and red once a category goes over — open the Cat list page to see which limit is in trouble. ⚠N prefix means N receipts need attention.
• Budget limits: open the Cat list page and tap a category name to set its monthly limit (empty = remove).

• Add new expense: fill Date / Store / Amount, pick category, click Add (saves locally, then auto-syncs to ezBookkeeping if an API token is saved).
• Income: add paychecks the same way; the local income-summary also reads income straight from ezBookkeeping so a paycheck added anywhere shows up.
• ◀ ▶ browse past months (local data). Limits are monthly values; the colored number reflects the month you are viewing. Transaction list shows first 15 rows.
• Receipt photos: drop JPGs/PDFs in your receipts folder; bin/expenses-auto-import (every minute via systemd timer) OCRs, pushes with photo, and files them. Failures notify + persist in the widget. Paystubs are deliberately not auto-booked — you get a notification with a prefilled income comment instead (details in the guide's auto-import section).

Data

Everything lives in ~/.local/share/warren.expenses/:

File	What
expenses.json	local transaction list
income.json	manually added income
budgets.json	per-category monthly limits (created on first limit; never synced to ezBookkeeping)
ez.conf	ezBookkeeping URL, API token, optional EBK_SSH/EBK_DOMAIN/EBK_MCP_EXTRA_ENVS (chmod 600)

ezBookkeeping (optional)

Point the plugin at any ezBookkeeping server (Docker, remote box, whatever) — the helper reads the URL and token from ~/.local/share/warren.expenses/ez.conf, so no machine-specifics are hardcoded:

~/.config/omarchy/plugins/io.github.wardad52.expenses/bin/expenses set-token <TOKEN>
# URL defaults to http://localhost:9400; edit EBK_URL in ez.conf to change it

Self-hosting a fresh box with Docker (server-side):

docker run -d --name ezbookkeeping --restart unless-stopped -p 9400:8080 \
  -e EBK_SECURITY_ENABLE_API_TOKEN=true \
  -e EBK_SERVER_DOMAIN=localhost -e EBK_SERVER_ROOT_URL=http://localhost:9400/ \
  -v ~/.local/share/ezbookkeeping/data:/ezbookkeeping/data \
  -v ~/.local/share/ezbookkeeping/storage:/ezbookkeeping/storage \
  mayswind/ezbookkeeping:latest
# open http://localhost:9400, register, User Settings → Security → Generate API token (pick 365 days expiry)

Check/restart/recreate the server from the panel side: bin/ezb-status status|restart|recreate (reads EBK_URL and EBK_SSH from ez.conf). Manual sync anytime: bin/expenses sync.

Docs

• docs/expenses-guide.md — full guide: how ezBookkeeping works first-run to reconcile, plus the auto-import and duplicate-name-toast sections
• docs/troubleshooting.md — status/restart/recreate order and the auto-import pipeline internals
• docs/receipt-photos.md — how to shoot receipts for clean OCR + category mapping
• docs/links.md — official ezBookkeeping links

Remove

omarchy plugin remove io.github.wardad52.expenses

Local data (~/.local/share/warren.expenses/) and your ezBookkeeping server are untouched by removal.

Note: screenshots on this page have store names and amounts inside the panel blurred on purpose; the bar number stays visible so you can see the traffic-light color.