Skip to content

Welcome to beancount-blue

Release PyPI Build status License Python Versions

beancount-blue is a comprehensive, production-tested toolkit for Beancount and Fava. It provides automated Open Banking API integrations, machine-learning-driven auto-categorization, a native Fava web management interface, and essential accounting plugins.

Key Features

🏦 Automated Banking API Importers

Connect directly to UK and European bank APIs to ingest transactions and balances automatically: * Monzo: Native OAuth integration supporting personal, joint, Flex, pots, and child accounts. * Starling: Personal Access Token integration supporting primary accounts, categories, and spending spaces. * TrueLayer (Open Banking): Connect to major UK/EU banks and credit cards (Amex, Chase, Barclaycard, etc.).

🤖 Machine Learning Auto-Categorization

Includes a native machine learning categorization pipeline based on scikit-learn (SGDClassifier with TF-IDF vectorization): * Automatically trains on your existing ledger entries. * Predicts payees and counter-accounts with configurable confidence thresholds. * Automatically retrains when your ledger file is edited.

🌐 Fava Web Management Extension (BankSync)

An embedded web UI inside Fava: * Integrations Dashboard: Real-time table displaying configured bank integrations, latest balances, sync status, and errors. * Interactive Sync: Trigger API syncs and review imports directly from the browser. * In-Browser Configuration: Add new APIs (+ Add API) and edit configurations in a built-in Monaco YAML editor.

🧮 Core Accounting Plugins

  • Amortization: Spread multi-month expenses (e.g. annual insurance, subscriptions) evenly across time using automated equity balancing.
  • UK Capital Gains Tax: Calculate capital gains following HMRC rules (same-day rule, 30-day "bed and breakfast" rule, and Section 104 average-cost holding pools).
  • Clear Residual Lots: Automatically balances and cleans fractional leftover lots that accumulate when using the NONE booking method.
  • Auto-Tagger: Automatically applies tags to transactions based on involved accounts.

Installation

Install beancount-blue using pip:

pip install beancount-blue

Or using uv:

uv add beancount-blue

Documentation Guide