beancount-import

Import bank CSV, OFX, and QIF exports into beancount ledgers as categorized, deduplicated transactions.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Manually transcribing bank and credit card export files into a plain-text beancount ledger is error-prone: flipped sign conventions corrupt amounts, re-imported files double-book transactions, and guessed categories bury mistakes. This Skill stages every row, deduplicates against prior imports, suggests categories from the ledger's own history, and writes only after explicit user confirmation. ## Core Features & Use Cases - Format detection and normalization: Parses CSV, OFX/QFX, and QIF exports, confirming column mappings, sign conventions, and date formats once and persisting them to a config block for zero-question repeat imports. - Two-layer deduplication: Stamps every entry with an import-id (native OFX FITID or a normalized SHA-256 hash) so re-importing the same file is a guaranteed no-op, with fuzzy matching to catch manually entered duplicates. - History-based categorization: Suggests counter-accounts only from accounts already open in the ledger, with confidence levels and cited reasons, falling back to Expenses:Uncategorized when no prior exists. - Use Case: You download a May CSV export from your Chase checking account. The Skill stages 12 rows, skips 4 already imported, flags 1 suspected duplicate, categorizes the rest from your ledger history, shows a review table, and appends the confirmed entries with import-id metadata before validating with bea check or bean-check. ## Quick Start Import the attached bank export CSV into my beancount ledger at ./ledger.beancount under the account Assets:Bank:Checking and show me the review table before writing anything.

Frequently Asked Questions about beancount-import

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

FAQPage Schema
How do I import a bank CSV into a beancount ledger?

Point the Skill at the CSV export and your ledger file, naming the source account. It detects the column layout, confirms the sign convention and date format once, stages categorized rows in a review table, and appends entries only after you confirm.

How does beancount deduplication work when re-importing the same file?

Every imported transaction carries an import-id metadata line: the native OFX FITID when available, otherwise a SHA-256 hash of date, amount, raw description, and source account. Re-importing the same file matches these IDs exactly and adds zero new entries.

Does the importer support OFX and QIF files, or only CSV?

It supports CSV, OFX/QFX, and QIF exports. OFX is preferred when offered because its FITID field provides the strongest deduplication ID; QIF and CSV rows use hash-based import-ids instead.

Can it categorize transactions automatically from my ledger history?

Yes. It matches each row's payee against existing ledger transactions and suggests the most frequent counter-account with a confidence level and reason. It never invents accounts; unmatched rows go to Expenses:Uncategorized for your refinement.

What happens if the date format or sign convention is ambiguous?

The Skill asks you rather than guessing. When MDY versus DMY cannot be proven from the data, or debit/credit meaning is unclear, it pauses, persists your answer to a config block, and applies it silently on future imports.

When should I not use this import workflow?

Do not use it for reconciling statements against balances, migrating full history from Mint, Monarch, or QuickBooks, building reusable Python importers, or booking securities trades. Those route to the reconcile, migrate, importer-author, and options skills respectively.