Sign up, a book is provisioned as its own machine, you connect an agent to it, and the first thing you do is open accounts — because a posting to an account that was never opened is refused.

1. Get an account

app.countbean.com has two doors: Continue with Google, or email and a password. Either one works; neither is a waiting list.

2. Your book is a machine

A book is not a row in a shared database. It is a private git-versioned Beancount ledger on its own machine, reachable only through the authenticated control plane — there is no public address for your book, by design.

That machine stops when idle and starts again on your next request. The first call after a quiet stretch takes a second or two, and can briefly answer “starting up”. That is a cold start, not a broken credential — the usual mistake at this point is to go and reissue a key that was perfectly good.

3. Connect an agent

In Claude, run /countbean:init. It shows you a short code and a link, you open the link, choose which book to connect, and approve. Nothing is pasted and no key is ever shown.

If your browser is on another machine, /countbean:connect takes a key instead: open your book, Connect Claude → Create key, and paste the line it gives you. The key is shown once.

Do not pass a control_url. connect_book rejects an explicit one even when it is the correct /v1/books/<id>/api URL printed on the book page. Let the plugin resolve the endpoint.

Either path stores the connection in ~/.countbean/credentials.json, readable only by you, and takes effect on the next tool call — no restart, no environment variables.

4. Open accounts before you record anything

Beancount will not accept a posting to an account that was not opened first.

2026-01-01 open Assets:Bank:Checking USD
2026-01-01 open Liabilities:CreditCard USD
2026-01-01 open Income:Consulting
2026-01-01 open Expenses:Software

Ask the agent to set up a starter chart and it will compose exactly this and send it through open_accounts. Read accounts before you accept the suggestion — the currency on an open line cannot be changed later.

5. Put something real in it

/countbean:ingest ~/Downloads/statement-january.csv

The agent reads the file, maps rows to accounts, shows you a table, and only then writes. Every write is validated with bean-check server-side and committed to git. A rejected write returns REJECTED with the validator’s error and nothing lands — there is no half-saved state to clean up.

6. Look at it

/countbean:status for balances and the last few commits. /countbean:report for a styled HTML page or an Excel workbook. Or open the book in your browser for the full ledger UI — balance sheet, income statement, journals.

What there is not

No bank feeds, ever. You export a file from your bank, which is also why every bank in every country works on day one.

No data entry in the browser. The ledger UI is read-only and the proxy in front of it accepts GET and HEAD only. Every write goes through the agent or the API, so that every change has an author and a diff.

No import wizard. There is no screen where you map columns; you hand the file to the agent. A deterministic server-side importer is being built (#515).

No one-click export yet (#48) — see your data.

Something here wrong or missing? Put it on the board — it is public, and the reply is in the thread.

Getting started — the first ten minutes