Obsidian Stats logoObsidian Stats

Beancount Ledger

by mkshp-dev
5
4
3
2
1
Score: 35/100
New Plugin
Install Code

Description

This plugin has not been manually reviewed by Obsidian staff. Comprehensive financial dashboard with Beancount integration. Features unified entry management, live BQL queries, connection validation, auto-starting backend, and streamlined settings.

Reviews

No reviews yet.

Stats

stars
downloads
0
forks
0
days
NaN
days
NaN
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
0
commits

Latest Version

Invalid date

Changelog

See all version on GitHub

README file from

Github

Beancount Ledger

Plugin Logo

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

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:

  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 ☕

Sponsors