Beancount Accounting Skill

Beancount is a plain-text double-entry accounting system. This skill provides expertise for creating, editing, and querying beancount files.

Core Concepts

Double-Entry Accounting

Every transaction must balance to zero. Money flows between accounts:

• Debits increase Assets/Expenses, decrease Liabilities/Income/Equity
• Credits decrease Assets/Expenses, increase Liabilities/Income/Equity

Five Account Types

Account Naming

Use colon-separated hierarchical names starting with capital letters:

Type:Country:Institution:Account:SubAccount

Examples:

Assets:Checking:Centennial:Joint
Liabilities:Card:Chase:Sapphire
Expenses:Food:Groceries
Income:Salary:Employer

Transaction Syntax

Basic Format

YYYY-MM-DD flag "Payee" "Narration"
  Account1    Amount Currency
  Account2    Amount Currency  ; optional comment

Flags

• * – Cleared/completed transaction
• ! – Pending/needs review

Examples

Simple expense:

2026-01-03 * "Starbucks" "Morning coffee"
  Expenses:Food:Coffee    5.75 USD
  Liabilities:Card:Chase:Sapphire

Paycheck with multiple postings:

2026-01-15 * "Employer" "Bi-weekly salary"
  Assets:Checking:Main           3500.00 USD
  Expenses:Taxes:Federal          800.00 USD
  Expenses:Taxes:State            200.00 USD
  Expenses:Insurance:Health       150.00 USD
  Income:Salary                 -4650.00 USD

Transfer between accounts:

2026-01-10 * "Transfer to savings"
  Assets:Savings:Ally     500.00 USD
  Assets:Checking:Main   -500.00 USD

Amount Interpolation

One posting amount can be omitted – beancount calculates it:

2026-01-03 * "Grocery Store" "Weekly groceries"
  Expenses:Food:Groceries    125.43 USD
  Assets:Checking:Main  ; Amount calculated as -125.43 USD

Essential Directives

open / close

Declare account lifecycle:

2026-01-01 open Assets:Checking:Main USD
2028-12-31 close Assets:Checking:Main

balance

Assert account balance at start of day (catches errors):

2026-01-31 balance Assets:Checking:Main 4583.84 USD

pad

Auto-generate balancing entry between two dates:

2026-01-01 pad Assets:Checking:Main Equity:Opening-Balances
2026-01-02 balance Assets:Checking:Main 4583.84 USD

include

Split files for organization:

include "2026-01.beancount"
include "accounts.beancount"

option

Configure beancount behavior:

option "title" "Personal Finances"
option "operating_currency" "USD"

Metadata and Tags

Metadata

Attach key-value pairs to directives or postings:

2026-01-03 * "Amazon" "Office supplies"
  order-id: "123-456-789"
  Expenses:Office    45.00 USD
    category: "equipment"
  Liabilities:Card:Chase

Tags and Links

Group related transactions:

2026-01-15 * "Hotel" "Conference lodging" #work-travel #conference-2026
  Expenses:Travel:Lodging    299.00 USD
  Liabilities:Card:Chase

2026-02-01 * "Expense Report" "Reimbursement" ^conference-2026
  Assets:Checking:Main    299.00 USD
  Income:Reimbursements

BQL Queries

Beancount Query Language (BQL) provides SQL-like queries. Run with bean-query:

bean-query finances/2026.beancount "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY 1"

Common Queries

Account balance:

SELECT account, sum(position)
WHERE account ~ 'Assets:Checking'
GROUP BY 1

Monthly expenses by category:

SELECT MONTH(date), account, sum(position)
WHERE account ~ 'Expenses' AND year = 2026
GROUP BY 1, 2
ORDER BY 1, 2

Transactions for an account:

SELECT date, narration, payee, position, balance
WHERE account = 'Assets:Checking:Centennial:Joint'
ORDER BY date

Key BQL Functions

Working with Beancount Files

Reading Files

Before editing, read the beancount file to understand:

• Existing account structure
• Naming conventions used
• Transaction patterns
• Include file organization

Adding Transactions

1. Match existing account names exactly
2. Use consistent payee/narration style
3. Ensure transaction balances to zero
4. Add to chronologically appropriate location or include file

Validation

Run bean-check to validate syntax:

bean-check finances/2026.beancount

Common Patterns

Credit card payment:

2026-01-25 * "Chase" "Credit card payment"
  Liabilities:Card:Chase:Sapphire    500.00 USD
  Assets:Checking:Main              -500.00 USD

Investment purchase with cost basis:

2026-01-20 * "Fidelity" "Buy index fund"
  Assets:Investments:Fidelity:FXAIX    10 FXAIX {150.00 USD}
  Assets:Investments:Fidelity:Cash   -1500.00 USD

Mortgage payment breakdown:

2026-01-01 * "Rocket Mortgage" "Monthly mortgage"
  Liabilities:Loan:RocketMortgage     800.00 USD  ; Principal
  Expenses:Housing:Interest           900.00 USD  ; Interest
  Expenses:Housing:Escrow             300.00 USD  ; Escrow
  Assets:Checking:Main              -2000.00 USD

Best Practices

File Organization

• Use include to split by month or category
• Keep account definitions in main file
• Add transactions to appropriate include files

Account Hierarchy

• Be consistent with naming depth
• Use specific subcategories for visibility
• Group related accounts logically

Balance Assertions

• Add monthly balance assertions for bank accounts
• Reconcile against actual statements
• Catches data entry errors early

Error Prevention

• Always run bean-check after edits
• Use balance assertions frequently
• Keep transactions in chronological order

Additional Resources

Reference Files

For detailed syntax and patterns, consult:

• references/syntax.md – Complete directive reference with all options
• references/bql.md – Full BQL query language documentation
• references/examples.md – Common transaction patterns and workflows

Command Line Tools