Beancount Import

beancount-import

Turn a bank/card export file into categorized, deduplicated ledger entries — staged first, written only after explicit confirmation, idempotent on re-import.

This skill exists because the weekly export-to-ledger chore has three silent failure modes: a flipped sign convention corrupts every amount, a re-imported file double-books everything, and a guessed category buries mistakes the user won't find until tax time. The skill defuses all three the same way: it never guesses (ask once, persist the answer), it stamps every entry with an import-id so re-imports are no-ops, and it only ever suggests accounts that already exist in the ledger.

Prefer bea

Read beancount-init's references/bea-cli.md before running ledger commands: it defines explicit root/destination paths, JSON batches, checks, and safe retries. Without bea, use beancount-init's references/compatibility.md.

• CSV the mapper can represent: read references/bea-import.md. Pass the confirmed sign, mapping, account, rules and destination on every preview and apply. Keep rules in the ledger repository after confirmation. Run the additional ±3-day manual-entry duplicate review; CLI duplicate detection alone does not cover it.
• OFX/QIF or unsupported CSV semantics: run the normalization, dedup, suggestion and confirmation stages below, then use the shared JSON batch recipe, preserving import-id and flags. This also handles mixed per-row duplicate decisions that a single --duplicates policy cannot express.
• Tested Beangulp workflows: enable with bea engine enable beangulp (requires system libmagic), then bea ingest identify|extract|archive with the actual runner supplied via --config. Ordinary CSV needs no Beangulp.

The agent interprets the source and reviews the rows; bea validates and writes the approved directives. Do not append directive text on this path.

Scope — what this skill does and does not touch

Does: parse one export file per run; stage, dedup, and categorize its rows; append confirmed transactions (with import-id metadata) and any needed open directives to one existing file.

Does not: edit or delete existing entries; create the target file (it must already exist and be reachable from the main file — a file nothing includes silently swallows entries); fetch data from banks (see references/getting-data.md for how users export, incl. SimpleFIN); reconcile balances (that is beancount-reconcile — suggest running it after a large import); touch option, plugin, or include directives.

Read references/formats.md before parsing any new or format-changed source (repeat imports with a stored config stanza apply the stored mapping directly) and references/dedup.md before the dedup pass. Both encode edge cases that are easy to get wrong.

Workflow

Seven stages, in order: Discover → Normalize → Stage → Dedup → Suggest → Confirm → Write + Verify.

1. Discover

Find beancount files in the working directory:

fd -e beancount -e bean . | head -20
# fallback: find . -maxdepth 4 \( -name '*.beancount' -o -name '*.bean' \)

The "main" file has option/plugin/include directives at the top, or is the largest with open directives. Then establish:

• Source account — which open account this export belongs to (e.g. Assets:Bank:Checking, Liabilities:CreditCard:Amex). Map from the user's words or the file's contents; if ambiguous, ask — never guess which account an export feeds.
• Config block — for every source, including CSV through bea, a comment block at the top of the main file starting with ;; beancount-import config. It records, per source, everything learned on the first import so repeat imports ask zero questions. Re-read it rather than re-detecting.
• Append target — the file where this account's transactions live (main file or an included sub-file, possibly year-bucketed). It must already exist.
• Payee history — the ledger's existing payee→account patterns (the Suggest stage's training data).

Config block format — one source stanza per export source:

;; beancount-import config
;; source: chase-checking
;;   account: Assets:Bank:Checking
;;   format: csv  columns: date=1,desc=2,amount=3  date_format: MDY  sign: negative=outflow
;;   append_target: ./transactions/2026.beancount
;;   imports: 3
;; source: amex-card
;;   account: Liabilities:CreditCard:Amex
;;   format: csv  columns: date=1,desc=2,debit=3,credit=4  date_format: MDY  sign: debit=outflow
;;   append_target: ./transactions/2026.beancount
;;   imports: 1
;; source: other-bank
;;   account: Assets:Bank:Savings
;;   format: csv  columns: date=1,desc=2,amount=3,type=4  date_format: MDY  sign: type=D|W=outflow,C=inflow
;;   append_target: ./transactions/2026.beancount
;;   imports: 1

Bump imports: only when entries are written (a fully-deduped no-op changes nothing). For sources requiring custom normalization, when it reaches 3+, suggest once: "you've imported this source N times — want me to codify it as a tested beangulp importer via beancount-importer-author?" Simple CSV mappings already provide repeatable imports and need no graduation nudge. For CSV, also record the exact csv_mapping: including sign=bank|ledger, date_format: as a strptime format, and durable rules: path. These supplement the human-readable source settings; bea's cache does not preserve sign.

2. Normalize

Turn the file into normalized rows: date, amount (ledger sign), payee/description, pending?, native-id?. Read references/formats.md first. In brief:

• Detect CSV vs OFX vs QIF. OFX rows carry a FITID (the native ID — feeds dedup); CSV/QIF usually don't.
• First time seeing a source: propose the column mapping, confirm it with the user, persist it after the write confirmation to the config block. Repeat imports: apply the stored mapping silently.
• Map amounts to the ledger's sign convention for the source account — the full sign rules live in references/formats.md (canonical; same convention as beancount-reconcile). Debit/credit split columns, all-positive amounts with a type column, DMY vs MDY — when ambiguous, ask, never guess. A wrong guess here corrupts every row.

3. Stage

Build candidate transactions in memory — nothing touches the ledger yet. One candidate per normalized row: date, flag (! if the source marks it pending, else *), payee, source-account posting at the exact row amount, counter-account left for Suggest, import-id computed per references/dedup.md.