Beancount

What it is

Beancount is a double-entry bookkeeping language: you write transactions in a text file, Beancount reads them into memory, checks them and produces reports. Martin Blais began it in 2008 after learning double entry and finding the tools of the time fragile; John Wiegley’s Ledger was the inspiration, as the history doc says. It is free software under GPL-2.0-only, and Blais has written nearly all of the code himself.

It does not fetch data, host anything or keep versions. It is a strict reader of a file you own.

How it works

The journal holds dated directives: open and close accounts, transactions, prices, balance assertions, documents, notes. Blais’s comparison with Ledger and hledger states the stance plainly: “Beancount is highly pessimistic. It assumes the user is unreliable.” Every transaction must balance, there are no virtual postings, lots held at cost must match a lot that was added earlier, and balance assertions apply by date, not by file position. Python plugins run inside the load pipeline and can transform or check the directive stream.

Version 3, stable since June 2024, is trimmed down: importing moved to beangulp and querying to beanquery, and the web interface, Fava, is its own project (1.30.16, 2026-08-18).

Beangulp’s Importer class is small and worth reading. identify(filepath) says whether this importer handles a file. account, date and filename decide where the original is archived. extract(filepath, existing) returns new entries and may consult the existing ledger. deduplicate(entries, existing) marks, rather than drops, entries that look like ones already in the books, by setting __duplicate__ metadata; the code compares against existing entries within two days either side (its docstring says five). The import guide recommends a Git repository with a documents/ tree mirroring the chart of accounts, so every download is filed next to the account it fed.

Data and access

You hold everything. The journal is the data and is readable without Beancount. The Python API (beancount.loader.load_file) returns the parsed entries, errors and options; BQL answers SQL-like questions; Fava exports query results. There are no rate limits, keys or fees. History is not Beancount’s job: if you edit an entry, the old one exists only if Git kept it.

Agents

The core has no AI features and no MCP server. The ecosystem does. StdioA/beancount-mcp runs BQL and submits transactions to a local ledger (0.1.1 on PyPI, 2025-03-29). beanquery-mcp is an experimental read-focused server. plaintextaccounting.org lists Countbean (a Claude Code plugin and MCP server), Beanhand (receipts to entries) and Finzytrack. A commercial host, beancount.io, offers an OAuth-scoped MCP endpoint whose write tools commit to Git with an optional dry_run diff; it says the server itself shows no human approval dialog.

The strictness matters more than any of these. An agent that writes a wrong entry usually fails bean-check instead of quietly skewing a balance, which is the kind of check an agent can run on its own before a person looks.

Customers

Technical individuals, households and some sole traders and small firms; the README says it has been useful to “many users, companies, and foundations”. beancount has 6,065 GitHub stars and Fava 2,583 (GitHub API, 2026-10-10); plaintextaccounting.org counts about 103 committers and a mailing list of about 880. There are no review-site profiles. People who pick it praise the strict checks, the Python plugins, BQL and Fava; the costs are the learning curve and writing your own importers.

History

Version 1 (to 2013) was partly Ledger-compatible; version 2 was a complete rewrite with a new grammar, in maintenance from 2020; version 3 became stable in June 2024 and split the tools out. The latest release is 3.2.3 (2026-05-05).

For ownpurse

Beancount is kin: a local, exact, owner-held record that refuses what does not balance. Two things are worth taking. First, beangulp’s importer shape, identify, extract, archive the original and mark likely duplicates, maps directly onto an ownpurse connector writing to the drawer. Second, the pessimism: a record that will not load when it is wrong is the right base for agents.

The difference is where truth sits. Beancount’s truth is the normalized journal you edit; what the bank actually said survives only as a filed document. ownpurse keeps what each source reported as facts and derives the ledger, so a correction is a new fact and an as-of question has an answer. A Beancount export, and a Beancount importer that reads the ownpurse record, would serve the same people well.