Skip to content

README.md

Latest commit

 

History

History
205 lines (155 loc) · 13.7 KB

README.md

File metadata and controls

205 lines (155 loc) · 13.7 KB
Raw

Beancount.io logo

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

Star Beancount.io on GitHub Mobile CI Dashboard CI Python CI Skills CI Secret scan MIT license

Beancount.io income statement showing monthly net profit and detailed income and expense account trees

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

Monthly expenses shown as a stacked bar chart Expenses shown as an interactive account hierarchy treemap

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.

Mobile apps

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.

Beancount Mobile home dashboard with net worth trend and recent transactions Beancount Mobile reports with income, expenses, and category breakdowns Beancount Mobile balanced multi-posting transaction entry

Download Beancount on the App Store   Get Beancount on Google Play

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

Why developers build with it

  • 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.

What is here today

Package Status What you can build with it
dashboard/ Active web client Ledgers, journal, reports, Monaco editor, imports, collaboration, and an AI assistant. React 19 + TanStack Start + Apollo.
mobile/ Active iOS & Android client Native transaction entry, account views, budgets, receipt capture, ledger editing, light/dark themes, 13 locales, and runtime selection of a compatible self-hosted server. Expo + React Native + Apollo.
cli/ 0.1.0 Read and write directives, check and format files, run BQL and reports, manage remote ledgers, or chat with a local-ledger agent. Python + Typer. Includes vendored fava reporting library.
skills/ Active skills The agent-native accounting loop: scaffold a ledger, import bank exports with dedup, author tested beangulp importers, reconcile against statements, migrate from Mint/Monarch/QuickBooks, query your finances in plain language, run a month-end close, and record options trades — all confirm-gated and bean-check-verified.
backend-cluster/ Active backend The services behind the Beancount.io API: backend-v2 (GraphQL/REST gateway), ledger (rustledger-WASM ledger service), idl (OpenAPI specs + generated clients), and agent-box (Cloudflare Worker control plane for the Ask-AI sandbox). Run locally via deploy/docker-mac/ or self-host on one server via deploy/docker/.

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.

Choose your entry point

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

Web dashboard

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/.

Mobile app

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.

CLI and Python tooling

Requires Python 3.12 and uv.

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

The CLI reference covers local reads and writes, validation, formatting, queries, reports, authentication, and ledger management.

Coding agent (MCP)

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" }
    }
  }
}

Nine tools — BQL queries, file listing, reads, edits, API-key management, and bank import — plus twenty-eight URI-addressed resources an agent fetches without spending a tool call — the ledger's vocabulary (payees, currencies, tags, …), its analysis reads (trial balance, account reports, …), its linked banks, and file contents. Bank imports are drivable end to end after a one-time browser link, with dry_run on everything that writes. Each resource has a REST twin over the same service call. Every call re-authorizes, so access revoked mid-session is refused on the next one. The credential must be scoped to a single ledger. 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.

Quality bar

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

Package Run before opening a PR
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 skills/scripts/ci-check.py

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.

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.

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 is a derivative work of Fava's Python core, 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.

License

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