Use AI with Beancount: import, review, and query your ledger

Use AI to suggest accounts and explain transactions, then check the entries against your source documents before saving them. This guide takes a small fictional statement through categorization, review, validation, and a query you can verify.

Choose a hosted or local workflow below. The worked example uses a local sample file so you can reproduce each check before connecting AI to your own books.

Choose your workflow​

The hosted Assistant and MCP are Beancount.io integrations. Installing the open-source Beancount accounting engine does not add those services to a local ledger.

Before you start​

Have your source statement, the account it belongs to, and a list of permitted destination accounts. Keep the original statement so you can compare it with the result.

For the local walkthrough, install Beancount using the getting started guide. You will also need Beanquery to run the final query from a terminal. The example assumes USD throughout and no existing transactions in the sample file.

For real data, decide which information your AI tool may receive. Remove unnecessary identifiers before sharing a statement. A local ledger can still send data to a cloud model through an editor or MCP client. Check the client and model provider's data policies; keeping a file on your computer does not by itself keep its contents local.

1. Start with the source transactions​

Our fictional checking account starts August with 1,000.00 USD. Its statement contains three withdrawals and closes at 805.10 USD after those withdrawals:

date,payee,description,amount
2026-08-03,Office Depot,Printer paper,-45.00
2026-08-04,Cloud Hosting Inc,Monthly hosting,-120.00
2026-08-05,Amazon,Online purchase,-29.90

Negative amounts here mean money leaving the checking account. Confirm your bank's sign convention before importing; other exports and importers may use a different convention.

In the CSV converter, map these four columns and set the source account to Assets:Bank:Checking with currency USD. Leave Flip every sign off for this sample. Check that the source postings are negative. A provisional destination account is only a placeholder until you have reviewed the categories.

If you start with a receipt image or PDF, compare the extracted dates, amounts, currency, and transaction count with the original document before categorizing anything. Keep the source values intact while deciding the accounts.

2. Ask for categories with explicit limits​

Use a prompt that names the allowed accounts and leaves room for uncertainty:

Suggest a destination account for each row in this sample statement. The source account is Assets:Bank:Checking. Use only Expenses:Office:Supplies or Expenses:Business:Hosting. Return the original date, payee, amount, suggested account, and a short reason. If the description is insufficient, return NEEDS_REVIEW and explain what information is missing. Do not invent accounts, change amounts, or write to the ledger.

Provide the three CSV rows with the prompt. A useful result would look like this; model wording and suggestions can vary:

The prompt expresses your intent. It does not enforce permissions on a tool that can write files. Configure the client's approval controls before giving it access to a real ledger.

3. Resolve uncertainty and review the entries​

Check the receipt for the Amazon purchase. For this example, it identifies a USB-C cable for the office, and the reviewer assigns Expenses:Office:Supplies. Without that evidence, leave the row pending rather than accepting a guessed category.

Create a new file named review.beancount with the following complete example. It includes the account declarations and opening balance that the CSV does not contain. If you used the converter, compare its transactions with these reviewed entries; do not add both copies to the same ledger.

option "title" "AI bookkeeping review example"
option "operating_currency" "USD"
 
2026-08-01 open Assets:Bank:Checking USD
2026-08-01 open Equity:Opening-Balances USD
2026-08-01 open Expenses:Office:Supplies USD
2026-08-01 open Expenses:Business:Hosting USD
 
2026-08-01 * "Opening balance"
  Assets:Bank:Checking       1000.00 USD
  Equity:Opening-Balances   -1000.00 USD
 
2026-08-03 * "Office Depot" "Printer paper"
  Assets:Bank:Checking        -45.00 USD
  Expenses:Office:Supplies     45.00 USD
 
2026-08-04 * "Cloud Hosting Inc" "Monthly hosting"
  Assets:Bank:Checking          -120.00 USD
  Expenses:Business:Hosting      120.00 USD
 
2026-08-05 * "Amazon" "Online purchase; receipt: office USB-C cable"
  Assets:Bank:Checking        -29.90 USD
  Expenses:Office:Supplies     29.90 USD
 
2026-08-06 balance Assets:Bank:Checking 805.10 USD

The opening-balance transaction belongs to this empty practice ledger. In an existing ledger, use its established balance and account declarations instead of adding another opening balance.

Before accepting a proposed change, compare each transaction with its source row. Confirm the signs, currency, accounts, and supporting receipt. A familiar merchant name alone does not establish the purpose of a purchase.

4. Validate and reconcile​

Run Beancount's validator on the local sample:

bean-check review.beancount

The complete example should pass without errors. Its balance assertion checks the amount in checking at the start of August 6, after the three preceding withdrawals.

Confirm the result against the statement:

• Three statement transactions appear once each, in addition to the opening balance.
• Withdrawals total 194.90 USD.
• Checking holds 805.10 USD: the opening 1,000.00 USD less those withdrawals.
• Office supplies total 74.90 USD and hosting totals 120.00 USD.

If you leave the Amazon transaction pending, checking remains at 835.00 USD and the assertion fails by 29.90 USD. Investigate that difference; do not add an unexplained adjustment just to make the check pass.

bean-check catches syntax, account, balancing, and balance-assertion errors. It cannot establish that a receipt is genuine, that you selected the right expense category, or that every statement row is present. A transaction posted to the wrong expense account can still balance perfectly.

When something does not match​

Ask AI to explain discrepancies and point to the affected rows. Confirm the evidence before deleting a suspected duplicate or changing an amount.

5. Save the reviewed result and query it​

When you repeat this workflow with your own statement, merge only your reviewed transactions into your real ledger, then validate the combined file. Keep the fictional entries in the sample file. If you use Git, inspect the diff and commit through your usual workflow. Keep the source statement available for later reconciliation. The scriptable workflows guide covers repeatable local automation.

You can verify the sample's totals with Beancount Query Language. With Beanquery installed, run:

bean-query review.beancount "SELECT account, sum(position) WHERE account ~ '^Expenses:' AND date >= 2026-08-01 AND date < 2026-09-01 GROUP BY account"

The two expense totals should be 74.90 USD for office supplies and 120.00 USD for hosting. Inspect the query's date range and account filter as well as its output.

With an AI client connected to a ledger containing the sample, you can ask:

Query the sample ledger for August 2026 expenses grouped by account. Show the query and its results. Do not change any files.

Compare its answer with the same totals. A fluent answer is useful only when its numbers can be traced to the ledger.

Apply the review process in Beancount.io​

For statement files, open Import → Smart Import in your ledger's sidebar. Review the extracted rows, choose Source Account and Currency, and use AI Fill for destination-account suggestions. Correct the categories before submitting Import, whose button includes the transaction count. Check the resulting journal and balances in a sample ledger before processing a real statement. Verify that withdrawals reduce the source account; the CSV above is prepared for the local converter, and importers can interpret signs differently.

For the hosted Assistant, open Ask Beancount.io inside your ledger. Start with a question about existing entries. When it proposes a file edit, review the diff before approving it. Accepted imports and Assistant edits are recorded in Git so you can inspect or revert the changes.

For MCP, follow the client-specific setup instructions linked above and authorize the intended ledger. Ask for editLedgerFiles with dry_run: true before permitting an edit. Inspect the proposed contents and operation summary, then allow a separate write call only after review. The dry-run preview does not establish accounting correctness or guarantee that your client will ask permission before a later write.

Keep the review process as you automate​

Start with a small batch and record which suggestions you change. Turn repeated, confirmed mappings into explicit import rules or provide reviewed examples as context. Do not assume that a model permanently learns from a correction in a conversation.

Keep extraction checks, category review, and statement reconciliation separate. Each catches a different kind of error. For recurring imports, also check that importing the same source twice does not silently duplicate transactions.

Research supports this distinction between valid syntax and correct accounting. Figueroa Rosero and colleagues' January 2025 study evaluated small open-weight models on financial-ratio scenarios and transaction generation using structured prompts. Its results describe those models and tasks, rather than an accuracy rate for today's assistants or your import workflow. Judge your own workflow using checked source transactions and the corrections they require.

Tools for a repeatable local workflow​

Choose a tool for the part of the process you need to repeat:

• Beangulp provides an importer framework. It replaces the older beancount.ingest framework in Beancount 3.
• smart_importer is a separately installed package that adds machine-learning suggestions to importers. It is not a built-in LLM feature.
• Beanborg documents rule-based categorization, machine-learning suggestions, and optional ChatGPT predictions. Check its current setup and compatibility before adopting it.

For wider context, see the bookkeeping automation guide and the monthly accounting workflow guide.

Explore a larger example​

The public ledger below is separate from the three-transaction exercise. Use it to explore how accounts, transactions, and reports fit together before connecting AI to your own books.