Caution

• Recent release 1.4.0 has breaking changes for Beta testers (BRAT). I had to change the plugin name and id to make sure obsidian allows submission to community store. This does not work well with BRAT users. If you are using this plugin via BRAT, please reinstall it from BRAT settings. This will not affect existing beancount files.
• The plugin is now available in community store at https://community.obsidian.md/plugins/beancount-finance

---

Beancount Ledger

A comprehensive Beancount integration for Obsidian that transforms your vault into a powerful plain-text accounting dashboard.

📘 Full Documentation - Read the complete guide for features, configuration, and usage.

---

✨ Key Features

📊 Unified Dashboard - Net worth tracking, balance sheets, and interactive charts in one view

🔍 Live BQL Queries - Click to see

Embed dynamic financial data directly in your notes using named query directives

⚡ Smart Transaction Entry - Click to see

Quick transaction creation with account autocomplete and validation

Highlights:

• 📈 Real-time financial metrics and trend visualization
• 📝 Inline BQL queries with named query directives (bql-q:name)
• 💰 Complete transaction, balance, and commodity management
• 💹 Automated Price Fetching — runs bean-price on a schedule; new prices are deduplicated and appended to prices.beancount automatically
• 🔄 Direct Beancount file integration—no separate database

---

🔧 Requirements

This plugin integrates with your existing Beancount setup:

1. Python 3.8+
2. Beancount v3+: Install via pip install beancount
3. bean-query: Command-line tool for querying Beancount files (pip install beanquery)
4. bean-price (optional): For automatic commodity price fetching (pip install beanprice)
5. WSL Support (optional): Full compatibility for Windows users running Beancount in WSL

Note: bean-query and bean-price are separate packages from Beancount itself and require their own pip install commands.

---

📦 Installation

Manual Installation

1. Download the latest release from GitHub Releases
2. Extract files to <vault>/.obsidian/plugins/obsidian-finance-plugin/
3. Enable the plugin in Obsidian Settings → Community Plugins

BRAT Beta Installation

For beta testers who want to try the latest development version:

1. Install BRAT Plugin:

   • Install BRAT (Beta Reviewers Auto-update Tester) from Obsidian Community Plugins
   • Enable BRAT in your Community Plugins settings

2. Add Beta Plugin:

   • Open Command Palette (Ctrl/Cmd + P)
   • Run: "BRAT: Add a beta plugin for testing"
   • Enter repository: mkshp-dev/obsidian-finance-plugin
   • Select branch: dev (or master for stable)

3. Enable Plugin:

   • Go to Settings → Community Plugins
   • Find "Beancount Ledger" and enable it

BRAT will automatically check for updates and notify you of new versions. This is the recommended way to test beta features before official releases.

Note: Beta versions may have bugs. Always keep backups of your Beancount files and vault data.

---

🔒 Permissions & Privacy

This plugin requires elevated system access to integrate with your Beancount setup. The following is disclosed in accordance with the Obsidian Developer policies:

Permission	Why it's needed
Filesystem access (fs)	Reads and writes your .beancount ledger file(s) directly. These files typically live outside the Obsidian vault, so the standard Vault API cannot be used.
Shell execution (child_process)	Runs bean-query, bean-check, and bean-price — external CLI tools that are part of your Beancount installation. There is no Obsidian-native way to execute external processes.
Vault enumeration	Scans vault files to locate BQL shorthand template files configured in settings.
Clipboard access	Copies query results or transaction data to the clipboard when you use the copy action in the UI.

No data is ever sent to external servers. All operations are local to your machine.

---

🤝 Contributing

We welcome contributions! Please see our CONTRIBUTING.md for details.

Development Setup

# Clone the repository
git clone https://github.com/mkshp-dev/obsidian-finance-plugin.git
cd obsidian-finance-plugin

# Install dependencies
npm install

# Start development build
npm run dev

# Build for production
npm run build

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If this project helps your workflow, consider supporting its development with a ☕