beancount-migrate

Convert finance-app CSV exports into verified beancount ledgers with deduplicated transfers and opening balances.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? When a personal-finance app shuts down or you switch tools, you are left with one CSV export and no trustworthy way to convert it: categories do not map 1:1 to double-entry accounts, transfers appear twice (once per account), and a silently dropped row only surfaces months later as a wrong balance. This Skill converts the full export into a beancount ledger with receipts — every count and balance is reconciled against the source. ## Core Features & Use Cases - Source-aware parsing: Recognizes Mint, Monarch, and QuickBooks Online export formats (plus a generic category-tagged CSV path) with per-source references for dates, signs, and column conventions. - Confirmed mapping before conversion: Proposes account and category mapping tables for explicit user approval; unmappable categories go to Expenses:Uncategorized and are listed, never guessed. - Transfer deduplication and balance verification: Pairs double-recorded transfers into single transactions, computes opening balances from stated current balances, appends endpoint balance assertions, and validates with bea check or bean-check. - Use Case: You downloaded your full Mint history before the shutdown. Hand the CSV to the Skill with your current account balances, confirm the proposed account/category mapping, and receive a complete ledger plus a migration report proving every row and balance ties out. ## Quick Start Migrate my Mint export ./export.csv into a new beancount ledger — my checking balance is 2935.81 and my Amex owes 129.24.

Frequently Asked Questions about beancount-migrate

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

FAQPage Schema
How do I migrate my Mint export to beancount?

Provide the Mint transactions.csv export and your current account balances. The Skill proposes account and category mappings for your confirmation, converts all rows, merges duplicate transfer pairs, computes opening balances, and verifies the result with bean-check.

How are credit card payments and transfers handled during migration?

Transfer rows appear twice in exports, once per account. The Skill pairs rows with matching amounts, opposite directions, and dates within three days into a single two-posting transaction. Unpaired transfer rows are booked against Equity:Transfers-Review and listed in the report.

Which finance app export formats are supported?

Mint, Monarch, and QuickBooks Online transaction-list exports have dedicated parsing references covering date formats, sign conventions, and transfer categories. Any other category-tagged CSV with date, amount, description, category, and account columns can use the generic path after confirming the column mapping.

What happens if my stated balance does not match the converted history?

The endpoint balance assertion fails and the Skill reports the exact delta with likely causes such as missing export rows, pending transactions, or a wrong stated balance. It never adjusts amounts to force a pass; a residual posting is booked only with your explicit acceptance.

Can this skill import ongoing bank exports into an existing ledger?

No. This Skill targets one-time full-history migrations into a fresh ledger. For ongoing imports into an existing populated ledger, use the beancount-import skill; for statement reconciliation, use beancount-reconcile.

Does the migration handle investment holdings and lots?

No. Investment holdings, lots, and price history are not converted; they are surfaced as follow-up work in the migration report. The migration produces cash-basis books, and complex equity structures from QuickBooks require manual review.