Beancount — 18 Operations for AI Agents
Beancount ledgers are plain-text accounting: every transaction, balance, and assertion in version control. act101 navigates directives structurally, so agents audit and query financial records with the precision a ledger demands.
This page is the canonical reference an AI coding agent uses to refactor, query, and analyze Beancount code through the act MCP server. 18 operations available: 0 refactor, 18 query, 0 analysis. Each operation is callable from Claude Code, Cursor, Codex, OpenCode, or any MCP-compatible agent host. Click any operation for a stable anchor link suitable for citation.
Worked Beancount examples
act101 reads a Beancount ledger's open (account), commodity, balance, and transaction entries as declarations — a transaction is named after its own date rather than its payee or narration, since a transaction has no other identifier. skeleton and symbols disagree on an open account's own kind: variable from one, class from the other, for the identical directive. symbols covers only the accounts and commodities, dropping every transaction and balance assertion the skeleton reads. The unit of structure in this grammar is the top-level directive: Beancount has no nesting, so neither query reaches inside a transaction's own postings. Each example below is the verbatim output of the command shown, run against the file shown. Query outputs are pretty-printed with the timing block omitted.
Read the ledger's accounts, commodity, and transactions as a skeleton
consultancy.beancount books a freelance consultancy's finances: four open accounts, a USD commodity declaration, three dated transactions — an opening balance, a client invoice, and a software subscription — and a balance assertion on the checking account.
$ act query skeleton consultancy.beancountBefore
1900-01-01 commodity USD
2024-01-01 open Assets:Checking USD
2024-01-01 open Income:Consulting USD
2024-01-01 open Expenses:Software USD
2024-01-01 open Equity:Opening-Balances USD
2024-01-01 * "Opening balance"
Assets:Checking 5000.00 USD
Equity:Opening-Balances -5000.00 USD
2024-02-14 * "Acme Corp" "Consulting invoice #1042"
Assets:Checking 2500.00 USD
Income:Consulting -2500.00 USD
2024-02-20 * "Linear" "Monthly subscription"
Expenses:Software 49.00 USD
Assets:Checking -49.00 USD
2024-02-28 balance Assets:Checking 7451.00 USDOutput
{
"type": "Skeleton",
"declarations": [
{
"kind": "variable",
"name": "USD",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 1,
"column": 1,
"byte_offset": 0
},
"end": {
"file": "consultancy.beancount",
"line": 2,
"column": 1,
"byte_offset": 25
}
},
"name_range": {
"start": {
"file": "consultancy.beancount",
"line": 1,
"column": 22,
"byte_offset": 21
},
"end": {
"file": "consultancy.beancount",
"line": 1,
"column": 25,
"byte_offset": 24
}
}
},
{
"kind": "variable",
"name": "Assets:Checking",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 3,
"column": 1,
"byte_offset": 26
},
"end": {
"file": "consultancy.beancount",
"line": 4,
"column": 1,
"byte_offset": 62
}
},
"name_range": {
"start": {
"file": "consultancy.beancount",
"line": 3,
"column": 17,
"byte_offset": 42
},
"end": {
"file": "consultancy.beancount",
"line": 3,
"column": 32,
"byte_offset": 57
}
}
},
{
"kind": "variable",
"name": "Income:Consulting",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 4,
"column": 1,
"byte_offset": 62
},
"end": {
"file": "consultancy.beancount",
"line": 5,
"column": 1,
"byte_offset": 100
}
},
"name_range": {
"start": {
"file": "consultancy.beancount",
"line": 4,
"column": 17,
"byte_offset": 78
},
"end": {
"file": "consultancy.beancount",
"line": 4,
"column": 34,
"byte_offset": 95
}
}
},
{
"kind": "variable",
"name": "Expenses:Software",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 5,
"column": 1,
"byte_offset": 100
},
"end": {
"file": "consultancy.beancount",
"line": 6,
"column": 1,
"byte_offset": 138
}
},
"name_range": {
"start": {
"file": "consultancy.beancount",
"line": 5,
"column": 17,
"byte_offset": 116
},
"end": {
"file": "consultancy.beancount",
"line": 5,
"column": 34,
"byte_offset": 133
}
}
},
{
"kind": "variable",
"name": "Equity:Opening-Balances",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 6,
"column": 1,
"byte_offset": 138
},
"end": {
"file": "consultancy.beancount",
"line": 7,
"column": 1,
"byte_offset": 182
}
},
"name_range": {
"start": {
"file": "consultancy.beancount",
"line": 6,
"column": 17,
"byte_offset": 154
},
"end": {
"file": "consultancy.beancount",
"line": 6,
"column": 40,
"byte_offset": 177
}
}
},
{
"kind": "function",
"name": "2024-01-01",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 8,
"column": 1,
"byte_offset": 183
},
"end": {
"file": "consultancy.beancount",
"line": 11,
"column": 1,
"byte_offset": 292
}
},
"name_range": {
"start": {
"file": "consultancy.beancount",
"line": 8,
"column": 1,
"byte_offset": 183
},
"end": {
"file": "consultancy.beancount",
"line": 8,
"column": 11,
"byte_offset": 193
}
}
},
{
"kind": "function",
"name": "2024-02-14",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 12,
"column": 1,
"byte_offset": 293
},
"end": {
"file": "consultancy.beancount",
"line": 15,
"column": 1,
"byte_offset": 425
}
},
"name_range": {
"start": {
"file": "consultancy.beancount",
"line": 12,
"column": 1,
"byte_offset": 293
},
"end": {
"file": "consultancy.beancount",
"line": 12,
"column": 11,
"byte_offset": 303
}
}
},
{
"kind": "function",
"name": "2024-02-20",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 16,
"column": 1,
"byte_offset": 426
},
"end": {
"file": "consultancy.beancount",
"line": 19,
"column": 1,
"byte_offset": 552
}
},
"name_range": {
"start": {
"file": "consultancy.beancount",
"line": 16,
"column": 1,
"byte_offset": 426
},
"end": {
"file": "consultancy.beancount",
"line": 16,
"column": 11,
"byte_offset": 436
}
}
},
{
"kind": "block",
"name": "Assets:Checking",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 20,
"column": 1,
"byte_offset": 553
},
"end": {
"file": "consultancy.beancount",
"line": 21,
"column": 1,
"byte_offset": 600
}
},
"name_range": {
"start": {
"file": "consultancy.beancount",
"line": 20,
"column": 20,
"byte_offset": 572
},
"end": {
"file": "consultancy.beancount",
"line": 20,
"column": 35,
"byte_offset": 587
}
}
}
]
}The skeleton reports nine declarations: USD and all four accounts as variable, the three transactions named by their own date (2024-01-01, 2024-02-14, 2024-02-20) as function, and the balance assertion as block.
List the accounts and commodity as symbols
Assets:Checking, Income:Consulting, Expenses:Software, and Equity:Opening-Balances are the four accounts the ledger's transactions post to.
$ act query symbols consultancy.beancountBefore
1900-01-01 commodity USD
2024-01-01 open Assets:Checking USD
2024-01-01 open Income:Consulting USD
2024-01-01 open Expenses:Software USD
2024-01-01 open Equity:Opening-Balances USD
2024-01-01 * "Opening balance"
Assets:Checking 5000.00 USD
Equity:Opening-Balances -5000.00 USD
2024-02-14 * "Acme Corp" "Consulting invoice #1042"
Assets:Checking 2500.00 USD
Income:Consulting -2500.00 USD
2024-02-20 * "Linear" "Monthly subscription"
Expenses:Software 49.00 USD
Assets:Checking -49.00 USD
2024-02-28 balance Assets:Checking 7451.00 USDOutput
{
"type": "Symbols",
"symbols": [
{
"name": "USD",
"kind": "variable",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 1,
"column": 22,
"byte_offset": 21
},
"end": {
"file": "consultancy.beancount",
"line": 1,
"column": 25,
"byte_offset": 24
}
},
"visibility": "unknown"
},
{
"name": "Assets:Checking",
"kind": "class",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 3,
"column": 17,
"byte_offset": 42
},
"end": {
"file": "consultancy.beancount",
"line": 3,
"column": 32,
"byte_offset": 57
}
},
"visibility": "unknown"
},
{
"name": "Income:Consulting",
"kind": "class",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 4,
"column": 17,
"byte_offset": 78
},
"end": {
"file": "consultancy.beancount",
"line": 4,
"column": 34,
"byte_offset": 95
}
},
"visibility": "unknown"
},
{
"name": "Expenses:Software",
"kind": "class",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 5,
"column": 17,
"byte_offset": 116
},
"end": {
"file": "consultancy.beancount",
"line": 5,
"column": 34,
"byte_offset": 133
}
},
"visibility": "unknown"
},
{
"name": "Equity:Opening-Balances",
"kind": "class",
"range": {
"start": {
"file": "consultancy.beancount",
"line": 6,
"column": 17,
"byte_offset": 154
},
"end": {
"file": "consultancy.beancount",
"line": 6,
"column": 40,
"byte_offset": 177
}
},
"visibility": "unknown"
}
]
}symbols reports only five entries — USD and the four accounts — dropping all three transactions and the balance assertion entirely; the four accounts come back kind: class, disagreeing with the skeleton's variable for the identical open directives.
Query
18 query tools, the same on every supported language. Descriptions live in the shared reference: /docs/query-tools.
callers control_flow data_flow definition diagnostics effect_closure effect_summary fix_auto get_type graph import_organize interface mutations references repo_outline skeleton symbols symbols_batch