beancount-ask

Answers ledger questions with shown, re-runnable BQL queries against beancount files.

275|32|Updated Oct 2, 2020
One-click install
npx skills add https://github.com/bex-co/beancount-io --skill beancount-ask-bex-co
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: beancount-ask
Source: https://github.com/bex-co/beancount-io/tree/main/skills/.claude/skills/beancount-ask
Command: npx skills add https://github.com/bex-co/beancount-io --skill beancount-ask-bex-co

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Financial questions about a plain-text ledger often get answered with fluent but unverifiable numbers. This Skill guarantees every figure comes from an actual BQL query execution that is shown alongside the answer, so users can re-run and verify each result themselves. ## Core Features & Use Cases - Verified Query Answers: Runs read-only BQL via bea --json query (or bean-query fallback) and shows the exact query with every figure cited. - Tested Recipe Library: Ships tested BQL recipes for top expenses, category trends, net worth, monthly burn, subscription price creep, and anomaly detection, with sign-trap guidance (income negative, expenses positive, cost(position) for USD totals). - Strict Read-Only Scope: Never modifies the ledger; clarifies ambiguous questions instead of guessing, and names the right sibling skill when a write is needed. - Use Case: Ask "what subscriptions am I paying for and have any gotten more expensive?" and get NETFLIX identified with its 15.49 to 17.99 USD increase, backed by the shown queries. ## Quick Start Ask the assistant to analyze your beancount ledger, for example: "What were my biggest expenses last month in ./ledger.beancount?"

Frequently Asked Questions about beancount-ask

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I query my beancount ledger for spending reports?

Run read-only BQL queries against your ledger file, for example selecting sum(cost(position)) grouped by account over a date range. This Skill uses bea --json query when available, falling back to bean-query, and shows every query with the answer.

How to find subscriptions and recurring charges in beancount?

Group Expenses postings by payee and count occurrences; payees appearing roughly once per month with steady amounts are subscriptions. A per-payee history query then reveals price creep, such as a charge rising from 15.49 to 17.99 USD.

Why is income negative in beancount BQL query results?

Income accounts accumulate negative balances in double-entry accounting, so a salary of 3000 appears as -3000. Negate the value for prose or use neg(), while Expenses accounts accumulate positive and read naturally.

Can this skill edit or fix my beancount ledger file?

No, the skill is strictly read-only and never modifies, formats, or fixes any file. If an answer requires a write, such as adding price directives, it names the appropriate editing skill and stops.

Does beancount net worth from BQL reflect market value?

The standard net worth query over Assets and Liabilities returns book value at cost basis, not market value. Market value requires price directives and value(position); if prices are missing, the skill reports that limitation instead of a wrong number.