beancount-io is a free, open source finance & accounting project written in TypeScript and released under MIT. It has 641 GitHub stars, 41 forks and 4 open issues, and was last pushed 8 hours ago. On this registry it ranks #32 of 39 tracked projects in Finance & Accounting, with 5 head-to-head comparisons available.

What is beancount-io?

Beancount.io is an MIT-licensed, plain-text double-entry bookkeeping system built around a .bean ledger file that its users own, with a web dashboard, a bea command-line tool and Python library, native iOS and Android apps, and agent skills plus a remote MCP server for people who want AI agents to help keep the books.

What it is

Beancount.io keeps double-entry books in a plain-text .bean file rather than a proprietary database, and serves that one ledger to four surfaces: a web dashboard, the bea CLI with its Python library, native iOS and Android applications built with React Native and Expo, and agent skills for Claude Code and Codex alongside a remote MCP server. The project lives in the Beancount plain-text accounting ecosystem, is written in TypeScript, and carries the MIT licence; its topics include accounting, bookkeeping, double-entry, ledger, finance, fintech, GraphQL, and mobile-app.

It solves the lock-in and export friction of hosted accounting software. Books kept in a SaaS product can only be scripted or queried after exporting CSVs, and the records cannot be read without the vendor's application; here the ledger is a file the user owns, diffs, and backs up with Git. The project also removes the setup burden of installing Beancount itself, because one command installs bea and provisions its own engine.

Key capabilities

  • A plain-text .bean ledger shared unchanged by the dashboard, CLI, mobile apps, and agent workflows, so it can be diffed, backed up with Git, and opened in any editor.
  • The bea CLI and Python library, with subcommands including init, add transaction, check, and report balance-sheet; bea --no-input init books --currency USD --opening-balance "Assets:Checking 1000" scaffolds a ledger without prompts.
  • Income statement, balance sheet, journal, and account-tree reports in a web dashboard, with a live example ledger readable without an account or installation.
  • Native iOS and Android apps for adding transactions, reviewing finances, scanning receipts, and editing ledger files.
  • Agent skills for Claude Code and Codex plus a remote MCP server, where every agent write is checked and confirm-gated; bea init --existing reads an existing ledger and writes an AGENTS.md naming its root, includes, and plugins without touching any ledger file.
  • A self-hostable backend cluster for running the full stack on your own infrastructure, with GraphQL listed among the project's topics.

Who uses it and how

  • Plain-text purists who want double-entry accounting in files that outlive any application, work with Git, and open in any editor.
  • Developers who script, query, and build on their finances from Python and the terminal instead of exporting CSVs from a SaaS product.
  • Agent users who have Claude Code, Codex, or another coding agent import statements, reconcile accounts, and close the month under confirm-gated writes.
  • Existing Beancount keepers who bring their books as they are, since bea init --existing changes no ledger file.
  • Mobile users who add transactions, scan receipts, and edit ledger files on a phone while the same open ledger stays available from the web, terminal, Python, and agents.

Getting started

Sign up at beancount.io/sign-up and record an entry from the web journal or the mobile app's Add Transaction screen, or install the CLI with brew install bex-co/tap/bea on macOS and Linuxbrew or uv tool install beancount-io wherever uv and Python 3.12 or newer are available. From there, bea --no-input init books creates a ledger, bea add transaction records entries, and bea check validates them.

How it compares

The facts supplied for this entry list no paid products that the project replaces; within the plain-text lineage its topics name, Beancount and ledger, Beancount.io is distinguished less by its file format than by the surfaces layered over it, reading existing Beancount books unchanged through bea init --existing. It keeps the format and adds a dashboard, native mobile apps, a Python library, and agent skills, with the CLI and agent workflows usable without any hosted service.

When to use it โ€” and when not to

Self-hosting means operating a backend cluster rather than a single binary, so a team unwilling to run that infrastructure should use the hosted sign-up or stay within the CLI and agent workflows, which require no hosted service. The project is a poor fit for anyone who wants a managed product that hides the files, because the plain-text ledger is the point rather than an implementation detail. Much of the operational detail also sits outside the README, in the CLI tutorial and usage reference under cli/docs and the skills documentation under docs/skills, so a reader should expect to follow those links.

project readme (upstream, from github) โ€” read inline

Beancount.io logo

Beancount.io

Your money in plain text, forever.
Beautiful reports, a phone app, a terminal CLI, and AI agents that can actually do your books.

No lock-in. No database you can't read. Your ledger is a .bean file you own, diff, and back up with Git.

Live demo  ยท  Quickstart  ยท  Agents  ยท  Self-host  ยท  Contribute

Star Beancount.io on GitHub MIT license beancount-io on PyPI Join the Telegram chat

Plain-text ledger in, reports you can explore out โ€” open the live example, no sign-up.


Pick your way in

๐Ÿ‘€ Look first

Click through reports on a real example ledger. No account, no install.

Open the live demo โ†’

โŒจ๏ธ Terminal

One command installs bea; it provisions its own engine.

First transaction in 30s โ†’

๐Ÿค– Agent

Skills for Claude Code and Codex, plus a remote MCP server.

Hand your agent the books โ†’

Try it in 30 seconds

No install. No empty-ledger setup. Just record your first real transaction:

  1. Sign up at beancount.io/sign-up โ€” already have an account? Log in.
  2. Open your ledger (create one if prompted โ€” it takes seconds).
  3. Record a transaction โ€” on the web open your ledger's Journal and add an entry; on mobile tap Add Transaction. Try a coffee run: Expenses:Dining 12.50 paid from Assets:Checking.
  4. See it land โ€” check the journal, then watch the income statement and balance sheet update.

That's the whole idea: double-entry books you can read as plain text, with reports, phone, terminal, and agents on top of the same ledger.

Prefer the terminal? Same first transaction from the CLI

You don't install Beancount yourself โ€” one command installs bea, which provisions its engine for you.

brew install bex-co/tap/bea      # macOS / Linuxbrew
# or: uv tool install beancount-io   # anywhere with uv + Python 3.12+
bea --no-input init books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
cd books
bea add transaction "Coffee" --date 2026-08-02 \
  --posting "Expenses:Dining 12.50" --posting "Assets:Checking"
bea check && bea report balance-sheet

Checking now holds 987.50 USD โ€” validated, formatted, and readable as plain text.

Then: record two or three real transactions ยท open the live demo and click through the balance sheet and account trees ยท automate with the CLI tutorial or point your coding agent at the skills.

Already keep Beancount books? Bring them as they are: bea init --existing reads your ledger, writes an AGENTS.md that tells your coding agent its root, includes and plugins, and changes no ledger file. See bring an existing ledger.

Who this is for

Plain-text purists
Double-entry accounting in files that outlive any app, work with Git, and open in any editor.
Developers
Script, query, and build on your finances from Python and the terminal instead of exporting CSVs from a SaaS.
Agent users
Have Claude Code, Codex, or another coding agent import statements, reconcile accounts, and close the month โ€” every write checked and confirm-gated.

Every surface, one ledger

You want toโ€ฆ Use Start
Work from the terminal or scripts bea CLI and Python library CLI tutorial ยท reference
See polished reports in a browser Web dashboard Live demo ยท dashboard/
Track money on the go iOS & Android apps Mobile apps ยท mobile/
Let an agent do your books Agent skills and MCP Agents and MCP
Self-host the whole stack Backend cluster Self-host

Your ledger stays the same plain-text file across all of them โ€” hosted or local-first, with no hosted service required for CLI and skills workflows.

Mobile apps

Review your finances, add transactions, scan receipts, and edit ledger files from the native Beancount client. The same open ledger stays available from the web, terminal, Python, and agent workflows.

Download Beancount on the App Store   Get Beancount on Google Play

Explore the mobile product tour or run the Expo app locally.

Agents and MCP

Beancount.io is built for the agent era: your ledger is text an agent can read, and every write is validated and reversible.

  • Coding-agent skills (local ledger) โ€” sixteen beancount-* workflows for Claude Code and Codex: scaffold a ledger, record everyday entries, payroll runs, investment trades and property events, import bank and payment-processor exports without duplicates, reconcile against statements, migrate from Mint/Monarch/QuickBooks, query finances in plain language (including profit by client or project), explain balance-sheet movements, prepare supported accrual drafts, track invoices and bills with the payments against them, and run a confirm-gated month-end close. Install the skills (native Windows: Windows PowerShell 5.1) โ†’ ask your first question โ†’ first-month guide โ†’ migration guide; already in Beancount? bring an existing ledger. Unified suite distribution and OpenClaw/Hermes installation record the current publication and host compatibility limits.
  • MCP server โ€” point any MCP client at a deployment to query and edit a ledger from an agent. Also listed on the official MCP Registry as io.beancount/beancount (OAuth sign-in).
MCP connection details
{
  "mcpServers": {
    "beancount": {
      "type": "http",
      "url": "https://your-deployment/api-gateway/mcp",
      "headers": { "Authorization": "Bearer [REDACTED]" }
    }
  }
}

Tools cover BQL queries, file reads and edits, entry and receipt insertion, account renames, moving entries between files, statement parsing, bank import, and more. URI-addressed resources and accounting prompts support spending reports, month-end close, reconciliation and import categorization โ€” e.g. /mcp__beancount__close-month in Claude Code. Use tools/list, resources/templates/list, and prompts/list against your deployment for its current catalog. File edits, directive appends, and bank imports preview with dry_run, every call re-authorizes, and failures return a machine code plus the next call to make. Per-host notes for Claude, Claude Code, ChatGPT, Cursor, Copilot, OpenClaw, and Hermes Agent: MCP docs; contract: ADR 0007.

How it compares

Beancount.io Plain Beancount + Fava Spreadsheet / SaaS finance app
Your data Plain-text .bean files you own Plain-text .bean files you own Locked in a database / their cloud
Reports Web, mobile, CLI, and Python reports Web reports (Fava) Built-in, but not programmable
On your phone Native iOS & Android apps Browser only Native app, tied to the service
AI agents CLI, skills, and MCP built in Do it yourself No agent access
Self-host Yes โ€” hosted, local-only, or your server Yes, manual No
Cost / license Free, MIT Free, open source Subscription

Beancount.io stands on Beancount and Fava rather than replacing them โ€” existing ledgers keep working. Full credits: ACKNOWLEDGEMENTS.md.

Self-host

Hosted, local-only, or your own infrastructure โ€” same ledger either way.

bex PaaS โ€” one click
Provisions Postgres, Gitea on a persistent disk, the API, and the dashboard from the root Blueprint. First build can take 20โ€“40 minutes; see deploy/bex.

Your own server or laptop
deploy/docker/ โ€” persistent single-server install with automatic TLS.
deploy/docker-mac/ โ€” the full stack locally on macOS.

FAQ

Is my financial data private?

Yes. Your ledger is a plain-text file. Local CLI and skills workflows never require the hosted service; if you self-host, everything runs on your server. You choose where the file lives.

How is this different from plain Beancount or Fava?

Beancount.io builds on both (Fava ships inside the CLI). It adds native mobile apps, a one-install CLI, hosted or self-hosted collaboration, and first-class agent workflows โ€” while your .bean files remain standard Beancount that Fava and other tools can still read.

Can I migrate from Mint, Monarch, or QuickBooks?

Yes โ€” the migration guide converts an export and keeps importing without duplicating transfers.

Do I have to self-host?

No. Use the hosted service at beancount.io, run everything locally with the CLI, or self-host on one server with deploy/docker/. Same ledger either way.

Run from source

There is no root package to install; each package owns its dependencies and checks.

Web dashboard, mobile app, and CLI from this checkout

Web dashboard (Node.js 22, Yarn 4 via Corepack, plus a Beancount.io API endpoint):

cd dashboard && corepack enable && yarn install --immutable
cp .env.example .env && yarn dev   # http://localhost:5173

See the dashboard setup guide. Containers instead? deploy/docker-mac/ runs the full stack locally on macOS; deploy/docker/ is the persistent single-server install.

Mobile app (Node.js 20.19.4+, Yarn Classic):

cd mobile && yarn install && yarn start

See the mobile development guide.

CLI from this checkout:

cd cli && uv sync --all-groups && uv run bea --help

bea upgrade updates through whichever package manager installed it. Full command tree, automation contract, and exit codes: CLI reference and generated command reference.

Quality bar (run before opening a PR)
Package Check
Dashboard cd dashboard && yarn format:check && yarn lint && yarn test && yarn build
Mobile cd mobile && yarn format:check && yarn lint && yarn typecheck && yarn test:unit
CLI cd cli && make check-all
Skills python3 scripts/skills/ci-check.py

Every active package has path-filtered CI, and a repository-wide secret scan gates every push and pull request. Run scripts/lint-deadcode.sh from the repository root to check for unused files and symbols (scripts/fix-deadcode.sh applies removals; review the diff and rerun full checks).

For contributors: what's in this monorepo
Package What it is
dashboard/ Active web client: ledgers, journal, reports, Monaco editor, imports, collaboration, AI assistant (React 19 + TanStack Start + Apollo)
mobile/ Active iOS & Android client (Expo + React Native + Apollo)
cli/ Active bea CLI and Python tooling (releases)
skills/ One Beancount.io ledger suite with sixteen beancount-* workflows; install the versioned beancount-io plugin or the complete source collection.
backend-cluster/ Active backend: GraphQL/REST gateway, ledger service, IDL, and agent sandbox

The dashboard and mobile app are clients for the Beancount.io API served by backend-cluster/ โ€” hosted, or self-run. Skills have two audiences: Beancount users get skills/; repository contributors get .agents/skills/ (see .agents/AGENTS.md). The root .claude/skills links to .agents/skills so Claude Code and Codex share the internal workflows.

Contributing

Contributions are welcome across product UI, accounting workflows, accessibility, translations, tests, Python tooling, and agent skills. Start with the contributing guide, browse open issues and the public adoption roadmap, and keep changes focused on one package when possible.

Read our code of conduct before participating. Report vulnerabilities privately through the security policy.

If Beancount.io is the kind of open, programmable finance software you want to see more of, star the repository and help more developers find it.

Community

Acknowledgements

Beancount.io stands on Beancount and Fava โ€” the vendored fava package inside cli/src/fava ships as bundled subprocess resources in the single beancount-io distribution, and the rest of the plain-text accounting stack (beanquery, beangulp, rustledger) is used as unmodified upstream dependencies. Full credits and license compliance: ACKNOWLEDGEMENTS.md.

License

MIT ยฉ Beancount.io applies by default. The customer skill suite under skills/ uses MIT No Attribution (MIT-0), including its instructions, references, and fixtures. Upstream projects remain under their own licenses.

Frequently asked questions

Is beancount-io free to use?

beancount-io is open source under the MIT licence. There is no licence fee and no seat count โ€” you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does beancount-io do?

๐Ÿ’ฐ Double-entry bookkeeping made easy โ€” plain-text accounting for humans and AI agents. Polished iOS & Android app built with React Native + Expo.

What is beancount-io written in?

beancount-io is primarily written in TypeScript. Its source is publicly available at https://github.com/bex-co/beancount-io, and it has 641 GitHub stars.