Budget Vault

Most budgeting apps ask you to upload your bank statements and trust someone else's server with them. Budget Vault doesn't.

Every account, budget and transaction is a plain markdown file in your own vault, on your own devices. There is no company database, no account to create, and nothing to export when you leave — the files are already yours.

Out of the box the plugin makes zero network requests, so your financial history can't be uploaded, analysed or sold. There is exactly one thing that can change that, and only if you switch it on: if you hold money in more than one currency, you can ask the plugin to fetch daily exchange rates so those accounts can be added into your totals. It is off by default, the setup wizard asks about it outright, and when it is on it sends a three-letter currency code and nothing else — no balances, no account names, nothing about your vault. The rates are saved as an ordinary note in your budget folder that you can read, edit or delete.

Put your vault in iCloud Drive, Obsidian Sync, Dropbox or Syncthing and your budget follows you to every device — synced by a service you chose, not one we picked.

What it does

• Dashboard — spending trend, budget vs actual
• Transactions — search, filter and edit your full history
• Budgets — per category, per period, with live "left / over" feedback
• CSV import — drop a bank statement, review, commit
• Auto-categorisation — rules learned from your corrections
• Savings, accounts, owed money, subscriptions, tax — a screen each
• Payday-aligned periods, and full support on iOS and Android

Install

1. Copy manifest.json, main.js and styles.css into <your vault>/.obsidian/plugins/budget-app/
2. Settings → Community plugins → turn off Restricted mode → enable Budget Vault
3. Open it from the wallet icon

A setup wizard runs on first launch. On mobile, repeat step 2 once — Restricted mode is per-device.

Open the vault, not the budget folder. Obsidian loads plugins from <vault root>/.obsidian/plugins/, so Budget Vault only exists in the vault you installed it into. If you use Open folder as vault on Finances/ — the folder holding your budget — the plugin is simply not there: no wallet icon, no command, no error. It looks like a failed install and is not one. Opening that inner folder also creates a second .obsidian inside it, so the mistake sticks until you delete that folder and reopen the outer vault.

Where your data lives

One folder you choose, default Finances/Budget:

Finances/Budget/
├── Settings.md
├── Categories/          one file per category
├── Accounts/            one file per account
├── Budgets/             one file per period (YYYY-MM.md)
├── Transactions/
│   └── <Account>/YYYY-MM.md
├── Data/Categorisation Rules.csv
├── Tax/
├── Debts.md
├── Owed Money.md
└── Services.md

Ordinary markdown tables and frontmatter. Open them in any editor, diff them in git, keep them forever.

Note the two levels: Finances/ is an ordinary folder inside your vault, and Finances/Budget/ is what the plugin reads. Neither of them is the vault — that is the folder above them, the one holding .obsidian/. See the note under Install for what happens if you open one of them as a vault instead.

Two folders sit outside the budget folder, at the top of your vault, because what they hold isn't household data to load back in — it's something you asked the plugin to write out: Exports/ (CSV/Markdown transaction exports, and the Budget page's Export — your budget for the last month, quarter, year, a tax year or any two dates, as a PDF, an Excel workbook or CSV) and Reports/ (the one-note financial report, Markdown and/or JSON). Both default to those names but are yours to rename or relocate from the Transactions, Budget and Report pages, and both show you the exact path before anything is written.

Debts.md

Columns are read by position, not by header name, so keep all twelve in this order — a table missing one silently shifts every later value into the wrong field:

The plugin rewrites the whole table on save, so a file created through New debt always has the right shape. This matters only if you write one by hand.

CSV import

Any statement with Date / Description / Amount columns works. Discovery Bank, FNB, Capitec and Nedbank exports have been imported end to end, but nothing is hardcoded per bank — columns are matched by header, then by layout shape for headerless files, and you can map them by hand if neither resolves.

Sign conventions are verified, not guessed: where a statement carries a running balance, the amounts are checked against it, so a bank that lists money out as a positive number can't quietly import every expense as income. If it can't be verified, the review screen says so.

No supported bank? Build your own CSV with Date, Title and Amount columns — negative for money out.

Development

src/ holds small vanilla-JS modules — no framework, no dependencies. main.js is build output; never edit it by hand.

./build.sh

Then toggle the plugin off and on.

Design notes

The budget period is the one piece of the app whose behaviour isn't obvious from the code alone — it has two naming shapes, a pay-cycle phase, and its own income arithmetic:

• How a period is decided — shape, phase and income — diagrams of the whole flow, plus what is deliberately left unguarded
• ADR 0001 — periods are derived, not materialised
• ADR 0002 — the pay cycle is a number, not a name

Feedback

Settings → Budget Vault → Send feedback, or open the form. Nothing from your budget is attached — the button just opens the form in your browser.

Support Budget Vault

Budget Vault is free and always will be. If it's useful to you and you'd like to say thanks, you can send something via PayPal — entirely optional, and nothing in the plugin changes either way.

License

GNU Affero General Public License v3.0 © Ruan Pienaar

Use it, change it, share it — personally or commercially, free of charge. The condition is reciprocity: if you distribute a modified version, or run one where other people can use it over a network, those people get its source under this same licence.

Releases up to and including 1.11.11 were published under the MIT licence and stay MIT for anyone holding a copy of them. See NOTICE for the full licence history.