beancount-reconcile

Reconcile one beancount account against a bank or credit card statement.

275|32|Updated Oct 2, 2020
One-click install
npx skills add https://github.com/bex-co/beancount-io --skill beancount-reconcile-bex-co
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: beancount-reconcile
Source: https://github.com/bex-co/beancount-io/tree/main/skills/.claude/skills/beancount-reconcile
Command: npx skills add https://github.com/bex-co/beancount-io --skill beancount-reconcile-bex-co

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Manually checking whether a plain-text beancount ledger matches a bank or credit card statement is tedious and error-prone: sign conventions differ between assets and liabilities, pending-versus-settled timing shifts dates, and the only real proof of correctness is a balance assertion that beancount itself verifies. This Skill automates the diff, classifies every discrepancy, and lands a verified period-end balance assertion. ## Core Features & Use Cases - Statement normalization: Parses CSV exports or pasted PDF statement text, handling debit/credit columns, signed amounts, MDY vs DMY date ambiguity, and asset vs liability sign conventions. - Three-pass matching with classified diffs: Matches statement lines to ledger postings (exact, windowed, near-miss) and classifies discrepancies as missing-in-ledger, missing-on-statement, duplicate, amount-mismatch, or date-drift. - Append-only fixes with confirmation gate: Proposes missing transactions (categorized from payee history or Expenses:Uncategorized) plus a period-end balance assertion dated the day after the statement's last day, writing only after explicit user confirmation and verifying with bea check or bean-check. - Use Case: You ask "does my ledger match my May Chase statement?" and the Skill reports two missing transactions, one amount mismatch to fix by hand, and appends a passing balance assertion proving the account ties out. ## Quick Start Ask the assistant to reconcile your checking account by pointing it at your ledger file and a statement CSV, for example: reconcile ./ledger.beancount against ./statement.csv for Assets:Bank:Checking.

Frequently Asked Questions about beancount-reconcile

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I reconcile a beancount ledger against a bank statement?

Provide the ledger file and a statement (CSV export or pasted PDF text) and name the target account. The Skill normalizes the statement, diffs it against ledger postings, reports discrepancies by class, and after your confirmation appends missing transactions plus a period-end balance assertion verified by bea check or bean-check.

How does beancount reconciliation handle credit card statements?

Credit card accounts are liabilities, so statement purchases (often shown as positive numbers) normalize to negative ledger postings and payments to positive ones. The Skill detects the account type from its name and applies the correct sign convention, asking when the convention is ambiguous.

Why is the balance assertion dated the day after the statement ends?

A beancount balance assertion checks the balance at the start of its date, excluding transactions on that date. To assert the ending balance as of the last statement day, the assertion must be dated the following day so end-of-period transactions are included.

Can this Skill fix duplicate or mismatched transactions automatically?

No. The Skill is append-only: duplicates, amount mismatches, and ledger entries missing from the statement are reported for manual review, never edited or deleted. Only missing transactions and a balance assertion are appended, and only after explicit confirmation.

What happens when the ledger does not tie out to the statement?

The Skill refuses to append a balance assertion that would fail bean-check. Instead it reports the exact residual, ties it to the unresolved suspects, mismatches, or duplicates causing it, and asks you to resolve those by hand before re-running.

Does it work without the bea CLI installed?

Yes. Without bea, the Skill appends ledger text directly in date order and verifies with bean-check if available. When bea is installed it writes through bea add transactions and bea add balance, which validate the whole ledger before writing.