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

Type	Purpose	Normal Balance
`Assets`	What you own (bank accounts, investments)	Positive
`Liabilities`	What you owe (credit cards, loans)	Negative
`Income`	Money coming in (salary, interest)	Negative
`Expenses`	Money going out (food, rent)	Positive
`Equity`	Net worth, opening balances	Negative

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

beancount

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

Flags

```
*
```
- Cleared/completed transaction
```
!
```
- Pending/needs review

Examples

Simple expense:

beancount

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

Paycheck with multiple postings:

beancount

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:

beancount

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:

beancount

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:

beancount

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):

beancount

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

pad

Auto-generate balancing entry between two dates:

beancount

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:

beancount

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

option

Configure beancount behavior:

beancount

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

Metadata and Tags

Metadata

Attach key-value pairs to directives or postings:

beancount

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:

beancount

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

bash

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

Common Queries

Account balance:

sql

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

Monthly expenses by category:

sql

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

Transactions for an account:

sql

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

Key BQL Functions

Function	Purpose
`SUM(position)`	Aggregate amounts
`YEAR(date)` , `MONTH(date)`	Extract date parts
`COST(position)`	Get cost basis
`account ~ 'pattern'`	Regex match account

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

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

Validation

Run

bean-check

to validate syntax:

bash

bean-check finances/2026.beancount

Common Patterns

Credit card payment:

beancount

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:

beancount

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:

beancount

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

Command	Purpose
`bean-check file.beancount`	Validate syntax
`bean-query file.beancount "QUERY"`	Run BQL query
`bean-report file.beancount balances`	Balance report
`bean-web file.beancount`	Web interface

beancount-accounting

NPX Install

Tags

SKILL.md Content

Beancount Accounting Skill

Core Concepts

Double-Entry Accounting

Five Account Types

Account Naming

Transaction Syntax

Basic Format

Flags

Examples

Amount Interpolation

Essential Directives

open / close

balance

pad

include

option

Metadata and Tags

Metadata

Tags and Links

BQL Queries

Common Queries

Key BQL Functions

Working with Beancount Files

Reading Files

Adding Transactions

Validation

Common Patterns

Best Practices

File Organization

Account Hierarchy

Balance Assertions

Error Prevention

Additional Resources

Reference Files

Command Line Tools