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.

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.

_{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

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.

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

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 (choose one):

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

From a directory without a books subdirectory, create a ledger and record a purchase:

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 format -i main.bean
bea list transaction --limit 10
bea report balance-sheet

Checking now holds 987.50 USD. bea upgrade updates through the package manager that 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.

Coding agent skills (local ledger)

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. Continue through import, reconciliation, and an approved close with the first-month guide. Bringing history from another app? The migration guide converts a Monarch export and keeps importing without duplicating transfers.

For a reusable bank importer, follow the importer graduation guide: preserve existing CSV history, test extraction before writing, and repair changed headers through either installed agent.

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

The hosted service is also listed on the official MCP Registry as io.beancount/beancount, so clients that read the registry add it from there and sign in with OAuth (details). There are per-host notes for Claude, Claude Code, ChatGPT, Cursor, and GitHub Copilot in VS Code.

Twenty-six tools — BQL queries, file listing, reads, edits, entry and receipt insertion, appending directives as plain Beancount text, statement parsing, pull requests, collaborators, and bank import — plus sixty-three 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. Four prompts — spending report, month-end close, account reconciliation, and import categorization — hand an agent the ledger playbooks as workflows the user selects, such as /mcp__beancount__close-month in Claude Code. 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, and yarn mcp:agent-eval runs real Claude Code and Codex sessions through onboarding tasks and scores their answers and ledger changes (MCP agent journeys). 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:

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

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

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