How can we help?
Install BudgetNote, learn the core workflow, and get clear answers about local data, pricing limits, and first-run setup.
Getting Started
BudgetNote is a private desktop budgeting app built around fast manual entry, local data ownership, and a simple monthly review workflow.
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. You can sync it across devices using iCloud Drive, Dropbox, or Syncthing. BudgetNote simply reads whatever folder you point it to.
If Gatekeeper blocks the app, open it from System Settings → Privacy & Security after confirming the download came from budgetnote.net.
If SmartScreen appears, click "More info" then "Run anyway". Only download from budgetnote.net.
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.
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
Insights & Notes
Mindfulness over Mathematics
Adding a note isn't just metadata—it's mindfulness. By writing why you spent money ("Stressed from work", "Celebratory dinner"), you spot behavioral patterns that numbers alone can't show.
Entry Notes
Add context to specific transactions. These appear in the Insights Calendar, helping you map your mood to your spending. Search for "coffee" to see every time you noted it.
Month Notes
A dedicated scratchpad for the month. Use this to summarize life events ("Moved apartments", "Got a raise") that explain why the month's graph looks anomalous.
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. "Pay yourself first" by logging transfers to savings.
- Link income or transfers triggers
- Projected completion dates
- Confetti on completion
- Free: 1 Active Goal / Pro: Unlimited
Transfers Logic
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.
Couples Mode
Track Finances Together — Privately
Couples Mode lets two people share a BudgetNote vault while keeping individual spending private or fully merged. Everything stays local — no cloud accounts, no servers.
Shared Vaults
Point both devices to the same synced folder (iCloud Drive, Dropbox, etc.). BudgetNote detects the shared vault and enables dual profiles automatically.
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.
Mixed vs Combined Modes
Mixed: Keep personal expenses private while sharing household costs. Combined: Fully merge all transactions into one shared view.
Couples Mode uses your existing synced folder — there is no BudgetNote server involved. Both devices read and write to the same local vault files.
Streaks & Habits
BudgetNote gamifies consistency. The Streak system tracks your financial habits and rewards you for showing up.
The Streak Pulse
A living dashboard that monitors four dimensions of your financial health:
- Logging Consistency — are you tracking daily?
- Savings Progress — are your goals on track?
- Debt Repayment — are you chipping away?
- Mindfulness Notes — are you reflecting on spending?
Pro feature
Heatmap Calendar
A GitHub-style heatmap that visualizes your entire year at a glance. Toggle between three modes:
- Activity: See every day you logged a transaction
- Volume: How much you spent each day (darker = more)
- Savings: Days you saved money vs spent
- Includes "Streak Pills" to celebrate Zero-Spend days
Pro feature
Analytics & Charts
BudgetNote forces all analytics to run on-device. We calculate trends, averages, and predictions using your local Hledger journal files.
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 to generate a beautiful, printable HTML/PDF report of your month. ideal for archiving or sharing with a partner/accountant.
Shortcuts & Workflow
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 14+ curated color palettes including Miami Nights, Aurora, Tokyo, and more. Pro unlocks additional premium theme presets.
Accent Colors
Pro users can customize the primary accent color used across the entire interface, independent of the selected theme.
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.
Pro & Licensing
One-Time Purchase, Lifetime Access
BudgetNote Pro is a single $29.99 payment. No subscription, no monthly fees. Your license includes all future updates and a 30-day money-back guarantee.
Device Portal
Manage your Pro devices from a secure self-service portal. Use a magic link sent to your email — no passwords required. Activate, deactivate, or transfer devices anytime.
Device Limit
Each Pro license supports up to 2 active devices (any OS). If both slots are full, deactivate one from the Device Portal before activating a new machine.
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.
Data & Privacy
Your Data is Yours
BudgetNote follows a Strictly Local philosophy. We literally cannot see your data. There is no analytics SDK tracking your transactions.
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.
Troubleshooting
Common issues and how to fix them. If something isn't listed here, email [email protected].
The app won't open (macOS Gatekeeper)
Go to System Settings → Privacy & Security. You should see a message about BudgetNote being blocked. Click "Open Anyway". This only happens once. Always download from budgetnote.net.
Windows SmartScreen blocks the installer
Click "More info" on the SmartScreen popup, then click "Run anyway". This is normal for new apps without an EV code-signing certificate.
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?
BudgetNote auto-checks for updates on startup. You can also manually check via Settings → About & Updates → Check for Updates.
FAQ
Data & Privacy
Where is my data stored?
100% locally on your device inside your BudgetNoteVault folder as plain-text Hledger journal files. Your budgeting data never leaves your machine.
Do you have access to my financial data?
No. The desktop app keeps your budgeting data local. If you buy Pro or contact support, we receive purchase or support info, not your transactions.
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 has a free core version with tracking, exports, search, notes, core charts, Couples Mode, and limited tags, limits, goals, templates, and payment methods.
Is this a subscription?
No. BudgetNote Pro is a one-time $29.99 payment for a lifetime license. No monthly fees, ever.
Can I use Pro on multiple devices?
Yes. Each Pro license supports up to 2 active devices on any OS (Mac, Windows, or Linux). Manage them from the Device Portal.
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, 1 savings goal, 3 templates, and 4 payment methods. Couples Mode and core charts are included free.
What is Couples Mode?
Couples Mode lets two people share a vault through a synced folder. Each person has their own profile, and you can view finances individually or as a combined Household. Available on both Free and Pro.
What are Streaks?
The Streak Pulse (Pro) tracks four habits: logging consistency, savings progress, debt repayment, and mindful spending notes. The Heatmap Calendar visualizes your activity over time.
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?
Not yet. BudgetNote is desktop-first today. Mobile is being explored for the future.
Can I sync between devices?
Yes, you control it. Place your BudgetNoteVault folder in a synced location like Dropbox, iCloud Drive, or Google Drive. Point BudgetNote on each machine to that synced folder.
Does it work offline?
Absolutely. BudgetNote is 100% offline-first. No internet connection is ever required for budgeting.
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.