Give your AI agent a ledger
Turn a task into books you can inspect. Give your shell-capable agent the bea CLI to record transactions, check its work, and return a balance backed by plain text.
Install bea
Choose your installer, then check the version. Local books need no Beancount.io account.
uv · Python 3.12+
uv tool install beancount-ioHomebrew · macOS or Linux
brew install bex-co/tap/bea
2026-08-02 * "Coffee"
Expenses:Dining 12.50 USD
Assets:Checking -12.50 USDPlain text. Yours to keep.
Local .bean files you can read, diff, and version with Git.
A check before every change.
Default CLI additions must validate before your ledger is replaced.
Bring the agent you use.
A shell-capable agent, one task, and commands you can inspect.
What you need
A terminal, a network connection, and either Homebrew or uv with Python 3.12 or newer. Local bookkeeping needs no Beancount.io account — that only enters the picture for the optional hosted step below.
bea --versionExample verified with bea 0.1.0: the Python distribution is beancount-io and the executable it installs is bea.
One small task. A real set of books.
Start with 1,000 USD. Record a 12.50 USD coffee. Ask your agent to check the ledger and show the query behind its answer.
Agent task prompt
You have shell access and the `bea` CLI installed. First run `bea --help` and read what it offers. Then, in a NEW empty demo directory (do not touch any existing ledger): 1) create a USD ledger opening Assets:Checking at 1000 on 2026-08-01; 2) add a 12.50 USD purchase narrated "Coffee" to Expenses:Dining on 2026-08-02; 3) run `bea check`; 4) report the Assets:Checking balance together with the exact BQL query you used. Expected result: 987.50 USD.- Create a fresh demo ledger
- Record the coffee purchase
- Check the books and query the balance
Expected result: Assets:Checking holds 987.50 USD.
Run it yourself, command by command
bea --no-input init demo-books --currency USD --date 2026-08-01 --opening-balance "Assets:Checking 1000"
cd demo-books
bea add transaction --date 2026-08-02 --narration "Coffee" --posting "Expenses:Dining 12.50" --posting "Assets:Checking"
bea check
bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"Put your agent to the test.
Three bank transactions. One recorded agent run. Download the same inputs, reproduce the result, and inspect what happened along the way.
Read the recorded runSynthetic data, verified with bea 0.1.0. One observed run; the full record includes failures and limitations.
The exact challenge inputs
A starter ledger, a bank statement, and category rules.
Take it beyond the demo.
Two copyable recipes build on the demo above: import a bank CSV with agent-proposed categories, then answer a balance question from query output. Each pairs an agent prompt with CLI equivalents and expected results.
Read the agent recipesChoosing between tools? Beancount.io is one of five compared on the same agent-workflow criteria, with dated sources.
Read the five-tool comparisonA few things before you start.
Your books stay on your machine
Every command below works on plain-text .bean files in a directory you choose. New ledger files are private to your user, and each addition is validated against the complete ledger before the file is replaced — on the default local CLI path, an unknown account or an unbalanced transaction is an error with guidance, and the file is left untouched.
Do I need a Beancount.io account?
Not for anything on this page. Installing bea, creating a local ledger, recording purchases, and checking balances all work without an account. You only sign in for the optional hosted extras: bea ask, the MCP server, and hosted ledgers.
Does installing the CLI set up my AI agent?
No. Installing gives you the bea command; your agent stays exactly as it is. You paste the task above into the shell-capable agent you already use, and loading agent skills is a separate step of its own.
Does my ledger leave my machine?
Local commands work on local .bean files and make no network calls. Only the hosted commands — bea cloud and bea ask, whose model calls run through the hosted AI proxy — talk to Beancount.io services.
What happens if my agent writes a bad entry?
On the default local CLI path, every addition is checked against the complete ledger before the file is replaced. An unknown account or an unbalanced transaction fails with guidance and leaves your file untouched — have the agent run bea check after any hand edit, too.
What exactly does bea ask need?
Two things beyond this page: the ask dependency extra and hosted credentials to sign in with. The default bea installation intentionally omits the AI dependencies until you ask for them.
Connect hosted tools when you need them
Local CLI commands work without a Beancount.io account. Hosted AI help and MCP access are separate, optional connections.
bea ask answers questions about a local ledger through the hosted AI service. It needs the ask extra — uv tool install 'beancount-io[ask]' — plus your Beancount.io credentials.
The MCP server and hosted ledgers likewise sign in with your Beancount.io account to authorize access. Start local; connect hosting only if you want it.
Agent skills for Beancount live in the product repository and load into your agent separately — installing the CLI does not install or configure them.
Explore the MCP connectionYour agent can do the bookkeeping. You can see the work.
Start with a local ledger and one verifiable result.