beancount-io

<p align="center">
  <a href="https://beancount.io/?utm_source=github.com&utm_medium=readme&utm_campaign=oss">
    <img width="96" src="https://beancount.io/img/favicon.png" alt="Beancount.io logo">
  </a>
</p>

<h1 align="center">Beancount.io</h1>

<p align="center">
  <strong>Agentic plain-text accounting, from every surface you work in.</strong>
  <br>
  Open-source web and mobile clients, a Python CLI and reporting library, and skills for coding agents.
</p>

<p align="center">
  <a href="https://github.com/bex-co/beancount-io"><strong>⭐ Star on GitHub</strong></a>
  ·
  <a href="https://beancount.io/">Web app</a>
  ·
  <a href="#mobile-apps">Mobile apps</a>
  ·
  <a href="#choose-your-entry-point">Start building</a>
  ·
  <a href="./CONTRIBUTING.md">Contribute</a>
  ·
  <a href="./.pm/README.md">Roadmap</a>
  ·
  <a href="https://github.com/bex-co/beancount-io/issues">Issues</a>
</p>

<p align="center">
  <a href="https://github.com/bex-co/beancount-io"><img src="https://img.shields.io/github/stars/bex-co/beancount-io?style=social" alt="Star Beancount.io on GitHub"></a>
  <a href="https://github.com/bex-co/beancount-io/actions/workflows/ci.yml"><img src="https://github.com/bex-co/beancount-io/actions/workflows/ci.yml/badge.svg?branch=main" alt="Mobile CI"></a>
  <a href="https://github.com/bex-co/beancount-io/actions/workflows/ci-dashboard.yml"><img src="https://github.com/bex-co/beancount-io/actions/workflows/ci-dashboard.yml/badge.svg?branch=main" alt="Dashboard CI"></a>
  <a href="https://github.com/bex-co/beancount-io/actions/workflows/ci-cli.yml"><img src="https://github.com/bex-co/beancount-io/actions/workflows/ci-cli.yml/badge.svg?branch=main" alt="Python CI"></a>
  <a href="https://github.com/bex-co/beancount-io/actions/workflows/ci-skills.yml"><img src="https://github.com/bex-co/beancount-io/actions/workflows/ci-skills.yml/badge.svg?branch=main" alt="Skills CI"></a>
  <a href="https://github.com/bex-co/beancount-io/actions/workflows/secret-scan.yml"><img src="https://github.com/bex-co/beancount-io/actions/workflows/secret-scan.yml/badge.svg?branch=main" alt="Secret scan"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
</p>

<p align="center">
  <a href="https://beancount.io/ledger/open_ledger/example/income-statement">
    <img src="./docs/images/income-statement-overview.webp" alt="Beancount.io income statement showing monthly net profit and detailed income and expense account trees">
  </a>
</p>

<p align="center">
  <sub>Turn a plain-text ledger into reports you can explore — <a href="https://beancount.io/ledger/open_ledger/example/income-statement">open the live example</a>.</sub>
</p>

<p align="center">
  <a href="https://beancount.io/ledger/open_ledger/example/income-statement"><img width="49%" src="./docs/images/income-statement-expenses.webp" alt="Monthly expenses shown as a stacked bar chart"></a>
  <a href="https://beancount.io/ledger/open_ledger/example/income-statement"><img width="49%" src="./docs/images/income-statement-expenses-hierarchy.webp" alt="Expenses shown as an interactive account hierarchy treemap"></a>
</p>

Beancount.io is a developer-friendly workspace for [Beancount](https://beancount.github.io/docs/) 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.

<p align="center">
  <a href="./mobile/README.md"><img width="31%" src="./mobile/docs/marketing-showcase/webp/01-home.webp" alt="Beancount Mobile home dashboard with net worth trend and recent transactions"></a>
  <a href="./mobile/README.md"><img width="31%" src="./mobile/docs/marketing-showcase/webp/04-reports.webp" alt="Beancount Mobile reports with income, expenses, and category breakdowns"></a>
  <a href="./mobile/README.md"><img width="31%" src="./mobile/docs/marketing-showcase/webp/09-add-transaction.webp" alt="Beancount Mobile balanced multi-posting transaction entry"></a>
</p>

<p align="center">
  <a href="https://apps.apple.com/us/app/beancount/id1527950512"><img height="48" src="https://beancount-io.b-cdn.net/app-store.png" alt="Download Beancount on the App Store"></a>
  &nbsp;
  <a href="https://play.google.com/store/apps/details?id=io.beancount.android"><img height="48" src="https://beancount-io.b-cdn.net/google-play.png" alt="Get Beancount on Google Play"></a>
</p>

<p align="center"><sub><a href="./mobile/README.md">Explore the mobile product tour</a> or run the Expo app locally.</sub></p>

## 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/`](./dashboard)             | Active web client           | Ledgers, journal, reports, Monaco editor, imports, collaboration, and an AI assistant. React 19 + TanStack Start + Apollo.                                                                                                                                                                                                                                                     |
| [`mobile/`](./mobile)                   | Active iOS & Android client | Public examples before sign-in, 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/`](./cli)                         | Active CLI · [releases](https://github.com/bex-co/beancount-io/releases?q=bea) | One-install `bea` CLI: directives, check/format/query, reports, cloud, and local-ledger ask. Frontend never loads Beancount — a managed engine (Homebrew at install, PyPI on first use) runs natives and the helper. Python + Typer. |
| [`skills/`](./skills)                   | Active skills               | The agent-native accounting loop: scaffold a ledger with one `bea` install (optional Fava), import bank exports with dedup, author tested beangulp importers (`bea engine enable beangulp`), 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 check-verified through `bea`.                                              |
| [`backend-cluster/`](./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/`](./deploy/docker-mac) or self-host on one server via [`deploy/docker/`](./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.

Skills have two audiences:

| Audience | Location | Workflows |
| -------- | -------- | --------- |
| Beancount users | [`skills/`](./skills/README.md), with implementations in [`skills/.claude/skills/`](./skills/.claude/skills) | The eight `beancount-*` ledger skills |
| Repository contributors | [`.agents/skills/`](./.agents/skills), documented in [`.agents/AGENTS.md`](./.agents/AGENTS.md) | PM, shipping, mobile releases, QA, code maintenance, and Mermaid diagrams |

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

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

```zsh
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](./dashboard/README.md) for environment variables and architecture.

Prefer everything in containers? [`dep