Claude + Beancount: Give AI Bookkeeping a Permanent Ledger

You run a clean categorization pass in Claude, then close the session. The structured record is gone, because a bare Cowork session has no database behind it. This guide walks the Claude and Beancount setup: a free, community-built way to give those books a plain-text ledger that survives every session.

How do you use Claude with Beancount to keep a permanent ledger?

Point Cowork at your bank statements and ask it to keep the books in Beancount. Beancount is an open-source, plain-text double-entry accounting system written in Python, with about 5,800 stars on GitHub. The whole ledger is one text file you own. It's git-friendly and portable. Open a fresh Claude session on the same file and pick up where you left off. To read the numbers, use Fava, Beancount's open-source web interface, with about 2,500 stars. It renders a trial balance, a balance sheet, and an income statement from the file. One caveat: this is a community pattern, not an official Anthropic skill. You wire it up yourself.

Key Takeaways

• A bare Cowork session forgets your books: a categorization run's output lives in a one-off spreadsheet unless you save it or hold it in a Project.
• Beancount is a plain-text ledger you own: open-source, written in Python, about 5,800 GitHub stars, git-friendly, and portable.
• The format is simple to read: five account types, one line per transaction, and postings that always balance to zero.
• One prompt starts it: point Cowork at your statements and ask it to keep the books in Beancount against a standard chart of accounts.
• Plain text means git works: commit the file each month, diff this month against last, and roll back a bad pass. A spreadsheet keeps no history.
• Fava shows the reports: the open-source web interface, about 2,500 stars, renders a trial balance, balance sheet, and income statement from the same file.
• It's a community pattern, not an official skill: Anthropic ships no Beancount plugin. You maintain the file yourself.
• It stops at scale: no pattern learning across a roster of 30 client books, and no built-in audit trail of who approved what.

The problem: a Cowork session forgets your books

A bare Cowork session has no database. When Claude categorizes a folder of bank statements, the result lands in a one-off spreadsheet. Useful, mostly right, worth a real read. But close the session and that structured record goes with it. Nothing persists behind it.

You can save the spreadsheet somewhere. You can build a Project to hold the context. Both work, sort of. But you're still stitching files and sessions together by hand.

Here's the deeper miss. That first-pass draft isn't a book of record. It's a snapshot. For the full picture of what a Cowork session can and can't do, read our guide to running Claude Cowork for bookkeeping. This is one narrow move inside the bigger question of how to put Claude on your books.

What's missing is a real ledger. A double-entry ledger that survives the session and holds the whole history in one place. That's where double-entry accounting with Claude and a text-file ledger comes in.

What Beancount is: a plain-text ledger you own

Beancount is an open-source, plain-text double-entry accounting system. It's written in Python. Its GitHub repo describes it in five words: "Double-Entry Accounting from Text Files." It has about 5,800 stars as of this writing.

Every account and every transaction lives in one plain text file. Because it's text, it travels well. It's git-friendly, so you can version it and see every change. It's portable, so you can hand it to a colleague or drop it in a shared folder. Open a fresh Claude session pointed at the same file, and Claude reads the whole history back.

Think of it like a QuickBooks Desktop file more than a cloud subscription. The file is yours. It sits on your disk. It doesn't vanish when a session ends. This is what people mean by plain text accounting: the books are a document, not a login.

One honest note. It's a text file you maintain yourself. There's no support desk. There's no automatic backup beyond what you set up. You own the upside and the upkeep.

The shape of a Beancount file: a short syntax primer

You don't have to write Beancount by hand. Claude writes it for you. But you'll read it, so it helps to know the shape. It's plain and short.

Every account is one of five root types. Assets, Liabilities, Equity, Income, Expenses. Each name is capitalized and split by colons, so you can nest as deep as you want. Here are five real accounts:

Assets:CheckingLiabilities:CreditCard:CITI-1234Equity:Opening-BalancesIncome:ConsultingExpenses:Groceries

Every account has to be opened before you use it. That's a one-line directive with a date:

2024-01-01 open Assets:Checking

Dates are always written year, month, day. A transaction starts with a date, then a flag, then an optional payee and a description in quotes. Under it come the postings, one account per line, each indented. Here's a single transaction:

2024-01-05 * "Farmer's Market" "Groceries" Expenses:Groceries 50.00 USD Assets:Checking

A few things to notice. The * is a flag. It means the entry is cleared and complete. If Claude isn't sure about a line, it uses ! instead, which marks it for review:

2024-01-09 ! "Unknown ACH" "Needs a second look" Expenses:Uncategorized 120.00 USD Assets:Checking

That ! is your flag pile. It's the fast way to see what Claude wasn't sure about.

The amount is a number, then the commodity in uppercase on the right, like 50.00 USD. The postings under a transaction always sum to zero. That's the double-entry rule, baked into the format. Money out of one account is money into another. Notice the second posting in each example has no amount. Beancount fills it in for you, since the whole thing has to balance. You can write both amounts if you want, but you don't have to.

Anything after a semicolon is a comment. Beancount reads right past it, so you can leave yourself notes:

; Rent went up in March, watch this account

Those are the pieces you'll see most: accounts, open, a dated transaction with * or ! flags, amounts, and comments. Beancount has more directives with names like close, balance, pad, price, and note. You'll meet balance in a minute. The rest you can pick up later. This much is enough to read your own books.

A worked example: a few transactions in one file

Here's what a small stretch of a real ledger looks like. Four accounts, three transactions:

2024-01-01 open Assets:Checking2024-01-01 open Income:Consulting2024-01-01 open Expenses:Software2024-01-01 open Expenses:Groceries

2024-01-04 * "Acme Co" "January retainer" Assets:Checking 3000.00 USD Income:Consulting

2024-01-06 * "Farmer's Market" "Groceries" Expenses:Groceries 50.00 USD Assets:Checking

2024-01-12 * "Cloud Host" "Monthly server bill" Expenses:Software 40.00 USD Assets:Checking

Read it top to bottom. First you open four accounts. Then money comes in: a $3,000 retainer lands in checking, and the other side of that entry is income earned. Then two bills go out: $50 for groceries, $40 for the server. Each one pulls from checking.

Do the math and checking holds $2,910. Income shows $3,000 earned. The two expenses sit in their own buckets, ready to roll up into a report. In each transaction the last posting had no amount, so Beancount worked it out. That's the whole ledger, in text, in order.

Open this same file in Fava and you'd see those numbers as a trial balance: checking at $2,910, consulting income at $3,000, and each expense on its own row. The report isn't a separate thing you build. It's the file, read back to you.

This is what Claude produces when you point it at your statements. Not a spreadsheet you have to re-save. A running file you add to.

Keep the books in Beancount: the step-by-step

Here's the setup, start to finish.

First, gather your statements in one folder. Bank statements, card statements, PDFs are fine, including scanned ones. Point Cowork at that folder.

Then ask Claude to keep the books in Beancount. Use this prompt:

Prompt: Use Beancount to keep the books for these statements. Use the QuickBooks default chart of accounts and stick to the Beancount format so the ledger stays valid.

Claude reads the statements. It writes each transaction as a double-entry posting into a .beancount ledger file. Debits and credits, every entry balanced. It flags anything it wasn't sure how to classify instead of guessing. Those are the ! lines from the primer above.

What you check: the classifications, and every flagged line. Treat the output like a new hire's first pass. Useful, mostly right, and worth a real read before you call it done. The same review habit applies here as anywhere else you put Claude to work on bookkeeping.

Next month, you don't start over. Point a new session at the same ledger and add to it:

Prompt: Here's my existing Beancount ledger. Add these new statements as double-entry transactions, match my existing account names and categories, and flag anything that doesn't fit a pattern already in the file.

The file carries the history. Claude reads it, matches your existing accounts, and appends. That's the whole point. The ledger remembers, so the session doesn't have to.

Which chart of accounts to use

Your chart of accounts is just the list of categories your money sorts into. The prompt above points Claude at the QuickBooks default set, and that's a fine place to start. It gives you the standard buckets every set of books needs: income, cost of goods sold, expenses, assets, liabilities, and equity.

The exact list matters less than one rule. Pick it once and keep it. Beancount only cares that the account names stay the same month to month. If January calls it Expenses:Software and March calls it Expenses:Software-Subscriptions, your report splits that spend across two rows. So when you ask Claude to add next month's statements, tell it to match the account names already in the file. That one instruction keeps the ledger clean over time.

The lines Claude flags, and why

The ! flag isn't random. A few kinds of line trip it every time, and they're the same ones that trip up any first pass. Knowing them makes your review fast.

The most common is a transfer between your own accounts. Move $2,000 from checking to savings and it looks like money leaving, but it isn't spending. It's your own cash in a different pocket. In Beancount that's two asset accounts and no expense at all:

2024-01-15 * "Transfer to savings" Assets:Savings 2000.00 USD Assets:Checking

A credit-card payment is the same trap. Paying the card isn't an expense. It moves a liability down. The expense already happened when you swiped. Then there's the opening balance with no statement behind it. Claude flags it because it can't see where that starting number came from.

So work the flagged pile first. Those are the lines that need your eyes. Once they're clear, spot-check the confident pile, then run your balance assertions. That order catches the most for the least effort.

Balance assertions: your check against the bank statement

There's one directive worth learning on its own, because it's how you keep the ledger honest. It's called a balance assertion.

A balance assertion is one line. A date, the word balance, an account, and an amount:

2024-02-01 balance Assets:Checking 1000.00 USD

It tells Beancount: this account holds exactly this much as of the start of this date. If the ledger disagrees, Beancount throws an error and points at the line. It won't let you pretend the books are fine when they aren't.

Here's how you use it to reconcile. Pull the closing balance off your bank statement. Say your checking account ends January at $1,000. You add a balance line dated February 1, the start of the next day, set to $1,000. Run Beancount. If it passes, your ledger matches the bank through the end of January. If it fails, something is miscoded or a transaction is missing.

That's a real honest-check, not a vibe. It's the plain-text version of ticking your books against the statement. Ask Claude to add a balance assertion for each account at each month's end, and you get a hard stop every month that either passes or tells you exactly where the books drifted.

Plain text plus git: version every change

Because the ledger is plain text, git works on it. And that changes what your books can do.

Git is version control. Every time you commit the file, git saves that exact state forever. Do it once a month, after each add, and you build a full history of your books over time.

A simple habit does it. After Claude appends the new month and your balance assertions pass, commit the file with a note like "closed January." Now that month is frozen in the history. Next month you add, check, and commit again. Over a year you get twelve clean snapshots, each one a moment your books balanced.

Now you can do things a spreadsheet can't. You can diff. Ask git to show you what changed between last month's commit and this month's, and it lists every line added or edited. You see exactly which transactions are new. You can also branch. Try a fresh re-categorization on a side branch, look at it in Fava, and either keep it or throw it away. Your main ledger never moves until you say so.

Compare that to a one-off spreadsheet. Change a cell and the old value is gone. There's no history, no diff, no going back. With git, every past state is still there. A bad categorization pass is a one-command undo, not a lost afternoon.

There's a quieter benefit too. The file lives on your own disk. It never leaves your machine unless you send it somewhere. If where your books live matters to you, that's a real point in favor of plain text. For more on that side of things, see how AI bookkeeping handles your data.

Running a couple of clients: one file per entity

The pattern stretches to a few sets of books. The rule is simple: one file per entity.

Your own books go in one .beancount file. A client's books go in a second. Another client, a third. Each file is self-contained. It has its own accounts, its own history, its own balance assertions. Nothing is shared between them.

For a couple of simple clients, this holds up fine. You keep three files. You run Fava on whichever one you're looking at. You commit each to git on its own. Each set of books stays clean and separate, which is exactly what you want when the work is small.

Be honest about the ceiling, though. That separation is the upside and the limit at once. A fix you make in one file never carries to another. Rename an account or sharpen a rule for client A, and client B knows nothing about it. You redo the same work by hand. That's workable for two or three. It's the exact thing that breaks when the roster grows, which we'll come back to.

See the numbers: Fava or a custom Claude view

A ledger file is great for storage. It's not much to read. That's what Fava is for.

Fava is Beancount's open-source web interface, with about 2,500 stars as of this writing. Its own description is plain: a web interface for the double-entry bookkeeping software Beancount, focused on features and usability.

Setup is short. Install it with one command:

pip3 install fava

Then point it at your ledger and start it:

fava ledger.beancount

Open http://localhost:5000 in your browser and there's your report view. It renders a trial balance, a balance sheet, and an income statement, straight from the file. It also shows account registers and charts, so you can click into an account and see every posting behind a number. There's an online demo too, if you want to look before you install anything.

One thing to hold onto: Fava runs locally. You host it. Nothing gets uploaded to a server. The page at localhost is coming off your own machine, reading your own file. That's the same ownership story as the ledger itself.

Prefer something more tailored? Ask Claude instead:

Prompt: Read my Beancount ledger and build a one-page owner summary: cash position, top expense categories this month, and anything that changed sharply from last month.

Same file, a custom view. No new tool to install.

The honest upkeep

Say the trade-off plainly, so nothing surprises you later.

You maintain the file. There's no support desk to call when something looks off. If a balance assertion fails at 9pm, you're the one who figures out why.

There's no automatic backup. Beancount doesn't save copies for you. If you don't set up git or your own backups, a lost file is a lost ledger. This is why the git habit above isn't optional if the books matter.

The pieces are yours to update. Beancount and Fava are mature open-source projects, but nobody maintains the wiring between them and Claude. If a future Claude update changes how Cowork writes files, you adjust the prompt and move on.

One more part of the deal. Beancount and Fava are free, but the workflow runs on Claude, and Claude runs on a paid plan with usage limits. A heavy month, or several client files in one week, can run into those limits. Check your plan's current caps before you lean on this for anything time-sensitive.

None of this is a reason to skip it. It's just the deal you're making. Full ownership on one side, full upkeep on the other. For one operator and one file, that's a fair trade. Know it going in.

This is a community pattern, not an official skill

Say this part plainly too. Anthropic does not ship a Beancount skill or plugin. This whole setup is a pattern the Claude user community worked out. It's not a supported feature.

That's not a knock. It works. It's free. Beancount and Fava have years behind them. But nobody at Anthropic or Intuit maintains the wiring for you. You're the operator here, not a subscriber.

If you're weighing this against the official route, it helps to know what Anthropic does support directly. Their Small Business plugin connects Claude to QuickBooks, and you can also connect QuickBooks Online to Claude on its own. Those are supported paths. Beancount is the free, do-it-yourself lane running alongside them.

Where a text-file ledger stops (and what runs the whole roster)

Give the trick its due. It's a clever, free way to give your own books a persistent ledger instead of a one-off spreadsheet. The same goes for a couple of simple clients' books. For one operator and one file, it's genuinely useful.

Now the honest limit. Three parts.

First, you're hand-wrangling text files. You maintain them. You back them up. You fix them when they break.

Second, there's no pattern learning across a roster. Run 30 client books this way and each ledger is its own island. A fix you make for one client never carries to the next. You saw that already with the one-file-per-entity setup.

Third, there's no built-in audit trail. Nothing records who approved which change, and when. For your own books, that's fine. Across a roster of clients, that gap gets real.

That's the exact line where a do-it-yourself text-file ledger stops and a productized book of record begins. Same review-and-approve work, built to carry volume a hand-maintained file can't. It's the same jump you face anywhere you scale Claude for accounting past your own single set of books.

That's why Growthy exists. It connects straight to QuickBooks Online. It pattern-learns per client from your fixes. It reviews every transaction with you before it posts. And it runs 10 to 30-plus client books with an audit trail. Growthy is 85% accurate on first import. You review the rest. And if your work runs into tax season, our sister product TracePrep handles tax workpaper automation. If a roster is where you're headed, see how AI bookkeeping handles many clients at once.

Get started with Growthy. Get started and see what it catches on your first import.

Frequently asked questions

A few more questions that come up when people set up Claude and Beancount for the first time.

What is Beancount, and why use it with Claude?

Beancount is an open-source, plain-text double-entry accounting system written in Python, with about 5,800 GitHub stars. Used with Claude, it gives a Cowork session a ledger that survives the session, instead of a one-off spreadsheet you have to remember to save.

What does a Beancount ledger look like?

It's plain text. Every account is one of five types: Assets, Liabilities, Equity, Income, or Expenses. Each transaction is a dated line with a short description, then a couple of indented postings that balance to zero. Claude writes it and you read it. If you can read a bank statement, you can read this.

Is the Beancount setup an official Anthropic feature?

No. It's a community pattern. Anthropic ships no Beancount skill or plugin. You wire up the pieces yourself and maintain the file.

Do I need to know how to code to use Beancount?

No, but you are maintaining a text file. Claude writes the entries and you review them. Being comfortable opening a plain-text file and reading it helps a lot.

How do I check my ledger against my bank statement?

Use a balance assertion. Add a one-line entry with the date, the word balance, the account, and your statement's closing balance. Beancount checks the ledger against that number and errors if they don't match. It's the plain-text way to reconcile.

How do I see reports from a Beancount ledger?

Use Fava, the open-source web interface, with about 2,500 stars. Install it with pip3 install fava, run fava ledger.beancount, and open http://localhost:5000. It renders a trial balance, a balance sheet, and an income statement from your file. Or ask Claude to build a custom view on the same file.

Does Fava send my data anywhere?

No. Fava runs locally on your own machine. The report page at localhost reads your file off your disk. Nothing gets uploaded to a server unless you send it somewhere yourself.

Can I use git with my Beancount ledger?

Yes, and it's worth doing. Because the ledger is plain text, git tracks every version. Commit the file each month and you can diff month to month, branch a re-categorization, and roll back a bad pass. It's also your backup.

Is a Beancount ledger really double-entry?

Yes. Every transaction posts to at least two accounts and has to balance to zero. It's the same double-entry rule QuickBooks enforces, just kept in plain text.

Can I share the ledger or move it between tools?

Yes. It's one text file, git-friendly and portable. Hand it off to a colleague, version it in git, or open a fresh Claude session pointed at the same file.

Does Claude remember my books between sessions?

The ledger file does the remembering, not the session. Point a new session at the file, and Claude reads the history back before it adds anything new.

Can I keep books for more than one client this way?

For a couple of simple clients, yes. Use one file per entity. It works when the number is small. It stops working as a roster grows, because a fix in one file never carries to the others.

When is Beancount not enough?

When you run many clients. You hand-maintain the files, there's no pattern learning across a roster, and no built-in audit trail of approvals. That's the point where a purpose-built tool fits better.

Is this a replacement for QuickBooks or Xero?

No. It's a plain-text ledger, not a connected accounting platform. For running client books at scale with an audit trail, a productized tool is the better fit.

The Beancount trick gives a Cowork session a ledger it remembers, for free, if you're comfortable maintaining a text file. It's a real upgrade over a one-off spreadsheet. And it stops right where running a roster of client books begins. Know both, and you'll know exactly when to reach for it, and when to reach for something built to scale.

Growthy is bookkeeping software, not a CPA firm. This content is educational, not professional advice.