personal-finance-beancount
This skill provides personal finance advice and Beancount/Fava guidance and includes a local analysis script scripts/analyze_beancount.py. It instructs running the script (e.g., python scripts/analyze_beancount.py /mnt/user-data/uploads/finances.beancount --all) and package installs like pip install beancount.
Personal Finance with Beancount & Fava
A professional AI assistant skill for personal finance management using plain-text accounting with Beancount and Fava.
Downloads: https://github.com/barcia/beancount-skill/releases Beancount MCP: https://github.com/barcia/beancount-mcp
Overview
This skill enables AI assistants to help users with:
- Financial Analysis: Interpret spending patterns, calculate metrics (net worth, savings rate, expense ratios)
- Beancount Expertise: Syntax help, transaction entry, account structure, and file organization
- Fava Mastery: Query creation, report generation, and visualization optimization
- Investment Guidance: Educational recommendations on asset allocation, risk assessment, and portfolio strategy
- Budget & Planning: Goal setting, cash flow management, and financial optimization
Contents
├── SKILL.md # Main skill definition and instructions
├── scripts/
│ └── analyze_beancount.py # Python script for quick financial analysis
└── references/
├── beancount_syntax.md # Complete Beancount syntax reference
├── beancount_query.md # BQL (Beancount Query Language) reference
├── fava_features.md # Fava interface, options, and budgets
├── fava_dashboards.md # Fava Dashboards plugin reference
└── financial_analysis.md # Financial metrics and analysis guide
Usage
As an AI Skill
The SKILL.md file contains the complete skill definition that can be used with AI assistants that support custom skills or system prompts. It provides:
- Workflow guidelines for financial analysis
- Professional standards and disclaimers
- Common use case patterns
- Reference to supporting documentation
Analysis Script
The included Python script provides quick financial insights from Beancount files:
# Install beancount first
pip install beancount
# Run analysis
python scripts/analyze_beancount.py your_finances.beancount --all
# Specific reports
python scripts/analyze_beancount.py your_finances.beancount --net-worth
python scripts/analyze_beancount.py your_finances.beancount --savings-rate --year 2024
python scripts/analyze_beancount.py your_finances.beancount --top-expenses 10
python scripts/analyze_beancount.py your_finances.beancount --monthly-expenses
Reference Documentation
The references/ folder contains comprehensive documentation:
| File | Description |
|---|---|
beancount_syntax.md | Complete syntax reference with all directives and examples |
beancount_query.md | BQL query patterns for common financial questions |
fava_features.md | Fava configuration, budgets, and workflow tips |
fava_dashboards.md | Creating custom dashboards with fava-dashboards plugin |
financial_analysis.md | Financial metrics, benchmarks, and optimization strategies |
Key Features
Multi-Language Support
The skill adapts to the user's language automatically - if the user writes in Spanish, it responds in Spanish; if in English, it responds in English.
Professional Standards
The skill maintains clear boundaries:
- Provides financial education and analysis, not licensed financial advice
- Recommends consulting professionals for major financial decisions
- Includes appropriate disclaimers for investment discussions
Practical Focus
- Actionable recommendations based on actual user data
- Concrete examples and working Beancount syntax
- Benchmarks and healthy financial ranges for comparison
Requirements
For the analysis script:
- Python 3.8+
- beancount (
pip install beancount)
License
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
Related Projects
- Beancount - Double-entry bookkeeping computer language
- Fava - Web interface for Beancount
- fava-dashboards - Custom dashboards for Fava