Beancount.io

Agentic plain-text accounting, from every surface you work in.
Open-source web and mobile clients, a Python CLI and reporting library, and skills for coding agents.

⭐ Star on GitHub · Web app · Mobile apps · Start building · Contribute · Roadmap · Issues

_{Turn a plain-text ledger into reports you can explore — open the live example.}

Beancount.io is a developer-friendly workspace for Beancount ledgers. Your books remain readable plain text while the surrounding tools add polished reports, transaction entry, Git-backed collaboration, automation, and access from the browser, phone, terminal, or a coding agent.

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

_{Explore the mobile product tour or run the Expo app locally.}

• Open, inspectable data — ledgers are text files that work with Git, scripts, editors, and the wider Beancount ecosystem.
• Useful at every layer — use the finished interfaces, automate local .bean files from Python, or build new workflows on the parsing and reporting library.
• Modern, typed stacks — React 19, React Native, TypeScript, GraphQL, Python 3.12, strict type checking, and package-scoped CI.
• Agent-ready workflows — the CLI and reusable skills give coding agents structured ways to create, validate, query, and update ledgers.
• MIT licensed — clients, developer tools, and libraries can be studied, adapted, and extended.

The dashboard and mobile app are clients for the Beancount.io API, served by backend-cluster/ — hosted, or self-run via deploy/docker-mac/. The CLI and ledger skills also support local-first workflows that do not require the hosted service.

Skills have two audiences:

The root .claude/skills links to .agents/skills so Claude Code and Codex share the internal development workflows.

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

Requires Node.js 22, Yarn 4 through Corepack, and a Beancount.io API endpoint.

cd dashboard
corepack enable
yarn install --immutable
cp .env.example .env
yarn dev

The app runs at http://localhost:5173. See the dashboard setup guide for environment variables and architecture.

Prefer everything in containers? deploy/docker-mac/ runs the full stack locally on macOS. For a persistent single-server installation with automatic HTTPS and durable Docker volumes, use deploy/docker/.

Requires Node.js 20.19.4 or newer and Yarn Classic.

cd mobile
yarn install
yarn start

Expo will guide you to iOS, Android, or a connected device. See the mobile development guide for the full workflow.

The beancount-io package installs one command, bea. You do not install Beancount yourself — Homebrew provisions a separate engine venv at install time; PyPI installs provision it on first local use. Install from the Homebrew tap or from PyPI:

brew install bex-co/tap/bea      # macOS and Linuxbrew
uv tool install beancount-io     # anywhere with uv and Python 3.12+

bea check                        # in a directory containing main.bean
bea format -i main.bean          # rewrite; default prints to stdout
bea upgrade                      # update through whichever manager installed it

Or from this checkout:

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

Start with the first-month tutorial, then use the CLI reference for the command tree, the --file/--json/--no-input automation contract, exit codes, validation, formatting, queries, reports, authentication, and ledger management. Every flag is listed in the generated command reference.

Give Claude Code or Codex the eight beancount-* ledger workflows. Install the skills with a sparse Git clone and one install command, then ask a sample ledger a first question with the first-query walkthrough.

Point an MCP client at a deployment to query and edit a ledger from an agent:

{
  "mcpServers": {
    "beancount": {
      "type": "http",
      "url": "https://your-deployment/api-gateway/mcp",
      "headers": { "Authorization": "Bearer bcio_your_ledger_scoped_key" }
    }
  }
}

Twenty-six tools — BQL queries, file listing, reads, edits, entry and receipt insertion, appending directives as plain Beancount text, statement parsing, pull requests, collaborators, API-key management, and bank import — plus sixty-four URI-addressed resources an agent fetches without spending a tool call: the ledger's vocabulary (payees, currencies, tags, …), its journals and analysis reads (trial balance, account reports, …), its linked banks, category suggestions, and file contents. Statements answer with totals and the accounts behind them rather than a chart payload, every failure names a machine code and the next call to make, and the transport's budget is sized for a whole agent session. Every eligible GraphQL operation now has a REST and MCP twin over the same protected service call — the parity gap is held at zero by CI. Bank imports are drivable end to end after a one-time browser link, with dry_run on everything that writes. Every call re-authorizes, so access revoked mid-session is refused on the next one. A credential can be pinned to one ledger or select ledger: "owner/name" per call. yarn mcp:conformance <base-url> tells you whether a deployment is connectable. See connecting an MCP client for the walkthrough and ADR 0007 for the endpoint's contract.

Every active package has path-filtered CI so unrelated changes stay fast:

A repository-wide secret scan also gates every push and pull request. Run scripts/lint-deadcode.sh from the repository root to check every executable package and support script for unused files and symbols. scripts/fix-deadcode.sh applies the available removals; review its diff and rerun the affected packages' full checks.

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.

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.

• Website: beancount.io
• Chat: Telegram
• Mobile: App Store · Google Play

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 how we comply with each upstream license: ACKNOWLEDGEMENTS.md.

MIT © Beancount.io — covers the code in this repository; upstream projects remain under their own licenses.