How can we help?
Install BudgetNote, learn the daily habit, and get straight answers about your data, what Pro costs, and what to do when something goes wrong.
Getting Started
BudgetNote is a budgeting journal you keep by hand. You write down what you spend as it happens — four seconds an entry — and once a week you sit with what you wrote. Everything stays in a folder on your own machine. Pro adds the weekly reflection layer and a paired phone.
Installation & Setup
BudgetNote runs locally on macOS, Windows, and Linux. On first launch, the desktop app creates a BudgetNote vault folder in your Documents directory.
This folder is your database. Keep it on local storage and include it in your normal computer backups. Pro couples can link two local vaults through BudgetNote's built-in end-to-end encrypted Couple Sync, so the live vault no longer needs to sit in Dropbox, iCloud, or another shared folder.
Double-click the app, then in System Settings → Privacy & Security click "Open Anyway" (once). If macOS says it "cannot be opened" or is damaged, run xattr -cr /Applications/BudgetNote.app once. Only download from budgetnote.net.
Install from Microsoft Store for the standard Windows setup and update experience. A signed x64 direct installer is also available.
Download the .AppImage file. Right-click → Properties → mark as executable, or run chmod +x from terminal.
The Dashboard
The dashboard is your daily driver. It provides a chronological view of your spending, grouped by month.
Month Cards
Toggle between months to see historical data instantly.
Quick Entry
Use Cmd+E to add transactions without touching the mouse.
Data & Privacy
Your Data is Yours
BudgetNote follows a strictly local philosophy. The desktop app ships no analytics SDK and reports nothing about your transactions back to us. (Our website uses ordinary page analytics, described in the privacy policy — it is entirely separate from the app.)
Since v0.1.7, BudgetNote uses the Hledger accounting engine. Your data is stored in plain-text .journal files you can read, edit, and own forever.
Go to Settings → Data to create manual backups and exports inside your local vault folder.
Moving computers? Copy the entire BudgetNoteVault folder to your new machine via USB or Cloud Drive.
BudgetNote includes built-in journal recovery. If the Hledger binary is missing, the app automatically loads your journals using its internal parser.
Your data stays in the local vault folder you control. The journal files are plain text and can be opened with any text editor or any Hledger-compatible tool.
Pro & Pricing
One-Time Purchase, Lifetime Access
BudgetNote installs free. Pro Single is a one-time $29.99 lifetime license key, and Pro Couple is a $49.99 bundle with two separate single-device keys. Pro also unlocks built-in Couple Sync and the phone app. No subscription, no monthly fees.
Mobile Sync
Pair the phone app from a licensed desktop to log money and check where you stand away from your computer. The desktop remains the main app and source of truth.
Device Portal
Manage activated devices from a secure self-service portal. Use a magic link sent to your email — no passwords required. Deactivate a device before moving that key to a replacement machine.
Device Limit
Each Pro license key activates one device at a time. The Couple plan includes two separate keys so each person can activate their own device.
License Activation
After purchase, you receive a license key via email. Enter it in Settings → Pro to activate. The key is tied to your device, not a cloud account.
Refund Policy
Not happy? Email [email protected] within 30 days for a full, no-questions-asked refund.
Core Concepts
Income vs. Expense
Many apps blend income and expense into a single "Net" number. BudgetNote keeps them strictly separate to help you understand your Cash Flow.
- Income (+): Paychecks, Dividends, Sold Items. Increases your "Inflow".
- Expense (-): Rent, Food, Travel. Increases your "Outflow".
Tags & Categorization
Transactions are organized by Tags. Free includes up to 10 custom tags, and Pro removes that cap.
Best Practices
Don't create ephemeral tags like #TripToVegas2024. Instead, use a generic #Travel or #Vacation tag and use the Note field for specifics.
Payment Methods
Tag each transaction with how you paid. This helps you track spending across credit cards, cash, Venmo, or any other method.
Free: 4 payment methods / Pro: Unlimited
Budget & Goals
Budgeting in BudgetNote is about Limits (capping downside) and Goals (planning upside).
Spending Limits
Set monthly hard caps on risky categories. The bar turns red as you approach the limit.
- Resets automatically on the 1st
- Applies to specific Tags (e.g. #Dining)
- Visual warning at 80% usage
- Free: 3 Active Limits / Pro: Unlimited
Savings Goals
Track progress towards big purchases, or plan a debt payoff with Avalanche and Snowball strategies and a projected debt-free date.
- Link income or transfers to a goal
- Projected completion dates and target-date pacing
- A closing reflection when you finish one
- Free: 1 active item, shared between savings goals and debt plans / Pro: unlimited
Transfers
Double-counting destroys analytics. The "Transfer" flag is your tool to tell BudgetNote: "This isn't spending, it's just moving money."
Credit Cards
When you buy dinner, that's spending (-$50). When you pay the Visa bill later, that is a Transfer, not a second expense.
Savings
Moving $500 from Checking to Savings is not 'spending' money. It's a Transfer. Your Net Worth remains the same.
Reimbursements
Bought lunch for a friend? Tag it #Reimbursable. When they Venmo you back, mark the inflow as a Transfer or Income.
When adding an entry, toggle the "Transfer" switch (or duplicate arrow icon) to exclude it from your Spending Graphs. It will still appear in your transaction history but won't skew your monthly burn rate.
Reflections & Notes
Why you spent it, not just what you spent
A note is the one piece of context your bank statement will never have. Writing down why money left — "stressed from work", "celebratory dinner" — is what turns a list of numbers into something you can actually learn from.
Entry Notes
Add context to a specific transaction. Notes are searchable, so looking up "coffee" brings back every time you mentioned it.
Month Reflections
A scratchpad for the month as a whole. Use it for the life events — "moved apartments", "got a raise" — that explain why a month looks nothing like the one before it.
The Weekly Reflection
A three-minute Sunday routine (Pro). Review the week against the one before it, judge your biggest purchases, note how the week felt, and commit to one specific thing for next week.
Graded Commitments
Next Sunday, that commitment is checked against what actually happened and reported as Kept, Partly kept, or Missed. Your own verdict always overrides the computed one, and free-text intentions are never graded.
The Regret Ledger
Your "was this worth it?" answers add up over time into what you have called not worth it, ranked by category, weekday, and mood. Amounts are stored as they were when you judged them, so editing an old transaction never rewrites your verdict.
The Reflection Center
Everything you have written in one place — entry notes, month reflections, Weekly Reflections, goal completions, and saved reports — with full-text search, filters by kind, year scoping, and Markdown export.
Couples Mode
Track Finances Together — Privately
Couples Mode lets two people budget in one household while each computer keeps a complete local vault. Built-in Couple Sync exchanges end-to-end encrypted changes through the relay—no shared cloud folder or shared login required.
Pair With One Code
On the first computer, open Settings → Shared Vault and choose Invite Partner's Computer. Send the single-use code privately; it expires after 24 hours.
Dual Profiles
Each person gets their own profile inside the shared vault. Transactions are attributed to the person who logged them.
Household View
A combined "Household" view merges both profiles into one dashboard so you can see total household income, expenses, and trends together.
Conflict-Safe Editing
Both partners can work independently. Disjoint edits merge automatically; true same-field or delete-versus-edit collisions appear as conflict cards instead of silently dropping data.
Encrypted Self-Repair
Each change has a sequence and encrypted base state. If a relay operation is missed, BudgetNote repairs from an encrypted snapshot without replacing local-only work.
The relay stores ciphertext and routing metadata, never a readable finance database. Existing folder-based couples can link in place, then use Move Vault Out of Synced Folder to return the live vault to local storage. Keep the old folder as a temporary archive until both computers are confirmed healthy.
The Phone App
Your Budget on Your Phone
The phone app is a Pro feature with three tabs: Add, Activity, and Sync. Log money in seconds, check where you stand, and let everything reach the desktop encrypted. The desktop app remains the source of truth for reporting and planning.
Pair by Scanning
Open Settings → Mobile Sync on a Pro desktop and choose Link a phone. Point the phone camera at the QR code, or type the one-time pairing code.
Add
A built-in amount keypad with quick math, one-tap templates, Today and Yesterday chips, rapid-fire entry with a running tally, description autocomplete from your real merchant history, voice capture, split transactions, and a 5-second undo.
Activity
Vault-wide history with search and filters, showing today's and this month's spend, budget meters, and goal and debt progress. It is cached on the device, so it still reads with no signal. Entries can be edited or deleted here.
Shared Catalog
The phone form uses your desktop tags, payment methods, goals, templates, and theme, and refreshes automatically after you save on the desktop.
Phone entries are encrypted before upload. The relay stores temporary ciphertext and routing metadata so your desktop can pull the entry later; it does not receive plaintext transactions.
Rhythms & Habits
Budgeting is a habit, and habits do not run on a daily chain that one busy Tuesday can destroy. Rhythms measures your practice by the week instead, so a missed day costs you nothing and a missed week is simply a week you can see.
Four Rhythms
Two run weekly, two run monthly:
- Capture — you logged at least one entry that week
- Reflection — you completed a Weekly Reflection or wrote a note
- Goal momentum — you moved a savings goal that month
- Debt momentum — you paid down a debt that month
Pro feature
Heatmap Calendar
A GitHub-style heatmap that visualizes your entire year at a glance. Toggle between three modes:
- Activity: every day you logged a transaction
- Volume: how much you spent each day (darker = more)
- Savings: days you saved money versus spent
- Click any active day to jump straight to those entries
Pro feature
A week in progress counts as pending, not missed. Rhythms leads with "N of the last 12 weeks" rather than a bare chain, and marks milestones at 4, 12, 26, and 52 weeks (3, 6, and 12 months for the monthly rhythms). Runs continue across year boundaries.
Analytics & Charts
All analytics run on your own device. Trends, averages, and projections are calculated from the Hledger journal files in your vault — nothing is sent anywhere to be computed.
Pro Advanced Suite
Visualize your financial consistency with a GitHub-style heatmap. See every day you spent money (Activity), how much you spent (Volume), or how much you saved (Savings).Includes "Streak Pills" to gamify your Zero-Spend days.
One click generates a printable HTML or PDF report for any period, measured against the period before it. Useful for archiving, or for sharing with a partner or accountant.
Shortcuts
Instantly opens a draft row. Type amount, tab to source, tab to tags. Hit Enter.
Universal search. Find transactions, tags, or settings instantly.
One-keypress filling. Map your most frequent purchases (e.g. 'Coffee', 'Groceries') to number keys.
Cheat Sheet
Customization
Make BudgetNote look and feel like yours. Themes, accents, animations, and language are all configurable.
Themes
Choose from 15 curated palettes, including Miami Nights, Aurora, Nordic, Obsidian, and Forest Canopy. Both a true-black dark mode and a full light mode are supported.
Accent Colors
Tune the accent colors used across the interface independently of the palette you picked, so the app can look like yours rather than ours.
Animations
Toggle between multiple animation styles or disable animations entirely for a snappier experience.
Language
BudgetNote supports 10 languages. Change language from Settings — the entire interface updates instantly.
Tag Color Palettes
Tags automatically adapt their colors based on the selected theme. No more manually picking hex codes — the palette is always harmonious with your chosen look.
Troubleshooting
Common issues and how to fix them. If something isn't listed here, email [email protected].
The app won't open on macOS (cannot be opened / damaged)
First try System Settings → Privacy & Security — you should see a message about BudgetNote being blocked; click "Open Anyway" (only needed once). If it still cannot be opened or is reported as damaged, open Terminal and run xattr -cr /Applications/BudgetNote.app, then launch it again. This only clears the download quarantine; the app itself is unmodified. Always download from budgetnote.net.
Windows SmartScreen blocks the installer
Prefer the Microsoft Store listing. SmartScreen may still appear for older direct installers while their signing reputation develops.
I see 'Read-Only Recovery Mode'
This means BudgetNote detected a problem with your journal file and is protecting your data from accidental overwrites. Try restarting the app. If it persists, check that your vault folder isn't read-only or locked by another sync app.
Hledger binary is missing
BudgetNote bundles Hledger binaries with release builds. If the binary is somehow missing, the app automatically falls back to its internal journal parser. Your data is safe — the app just switches to read mode until the binary is restored.
The app seems stuck or won't load
If the window doesn't appear within 10 seconds, the app forces visibility automatically. If it's still blank, try deleting the app cache (not the vault) and restarting. On Mac: ~/Library/Application Support/BudgetNote.
How do I update the app?
Microsoft Store builds update through the Store. Direct macOS, Windows, and Linux builds auto-check on startup, and you can manually check via Settings → About & Updates → Check for Updates.
FAQ
Data & Privacy
Where is my data stored?
In a BudgetNoteVault folder on your own device, as plain-text Hledger journal files you can read and back up. With Couple Sync, each partner keeps a complete local vault. If you turn on the phone app or Couple Sync, changes are encrypted on your device before passing through the relay and are merged back into those local vaults.
Do you have access to my financial data?
No. Your budgeting data lives in local vaults. The phone app and Couple Sync send only end-to-end encrypted changes plus routing metadata through the relay, so we cannot read your transactions, goals, or notes.
Is my data encrypted?
BudgetNote keeps your data local, but it does not add a separate encrypted vault layer yet. You can rely on full-disk encryption such as FileVault or BitLocker.
What happens to my data if the app shuts down?
Your data stays in the local vault folder you control. The journal files are plain-text and can be opened with any text editor or Hledger-compatible tool.
What is Hledger?
Hledger is an open-source, plain-text accounting engine. Since v0.1.7, BudgetNote uses Hledger to store your finances in human-readable .journal files — no proprietary format lock-in.
Licensing & Pricing
Is BudgetNote free?
Yes. BudgetNote installs free and includes tracking, exports, search, notes, core charts, and limited tags, limits, goals, templates, and payment methods.
Is this a subscription?
No. BudgetNote Pro Single is a one-time $29.99 lifetime license. Pro Couple is a one-time $49.99 bundle with two separate license keys. No monthly fees, ever.
Can I use Pro on multiple devices?
Each Pro license key activates one device at a time on any OS. If you need two people or two active devices, choose the $49.99 Couple plan, which includes two separate keys.
What is the refund policy?
We offer a 30-day money-back guarantee, no questions asked. Email [email protected] for a full refund.
Do I get future updates?
Yes. Your Pro license includes all future updates and new features for life.
Features
What are the limits on the Free version?
Free users get up to 10 tags, 3 spending limits, 3 templates, 4 payment methods, and 1 active savings goal or debt plan — goals and debts share the same slot. Core charts are included free. Couples Mode, the phone app, and the Weekly Reflection are Pro features.
What is Couples Mode?
Couples Mode lets two people link their computers with a single-use invite. Each computer keeps a complete local vault, encrypted changes sync through BudgetNote's relay, and each person has a profile plus a combined Household view. It is included with Pro, and the Couple plan includes two separate single-device keys.
What are Rhythms?
Rhythms (Pro) measures your budgeting practice weekly rather than as a daily chain: Capture and Reflection run weekly, Goal and Debt momentum run monthly. A week in progress counts as pending, never missed. The Heatmap Calendar visualizes your day-by-day activity alongside it.
What are Payment Methods?
Payment Methods let you tag transactions by how you paid (e.g., "Chase Visa", "Cash", "Venmo"). Free includes 4 methods. Pro unlocks unlimited.
What is a 'Transfer' and why use it?
A transfer marks money movement between your own accounts, such as moving cash from checking to savings. It keeps your spending analytics accurate by excluding internal moves.
Does BudgetNote support bank sync?
No. BudgetNote is intentionally built around manual entry and local-first budgeting instead of connected bank accounts.
Sync & Compatibility
What operating systems are supported?
macOS, Windows, and Linux (.AppImage). All three platforms get the same features.
Is there a mobile app?
Yes, Pro includes an installable phone app. It pairs from the desktop Mobile Sync settings and covers logging plus a read-only view of your spending, budget meters, and goal progress. Reporting, planning, and settings stay on the desktop.
Can I sync between devices?
Yes for Pro couples: built-in Couple Sync links two licensed desktops through an end-to-end encrypted relay, with one complete local vault on each computer. No Dropbox or iCloud folder is required. Pro Mobile Sync separately delivers encrypted phone entries back to the paired desktop and, for linked couples, to both partner computers.
Does it work offline?
Yes on desktop. BudgetNote is offline-first and your desktop budget works without internet. The phone app can queue entries locally, then needs a connection to deliver them to the desktop relay.
General
How do I contact support?
Email us at [email protected]. We typically respond within 24 hours.
Is the app open source?
The core app is not open source, but your data is stored in open plain-text Hledger journal files — always accessible and portable.
Where can I see what's new?
Check the Changelog for all release notes, or follow @BudgetNoteApp on X.
© 2026 YZEE Labs. BudgetNote — local-first financial tracking.