phoenixclaw-ledger

# PhoenixClaw Ledger: Zero-Effort Financial Tracking PhoenixClaw Ledger automatically extracts financial transactions from your daily conversations and payment screenshots, requiring zero manual input. ## Core Capabilities | Feature | Description | |---------|-------------| | **Semantic Expense Detection** | AI identifies spending mentions in natural conversation | | **Screenshot Recognition** | Extracts transaction data from payment app screenshots | | **Smart Categorization** | Auto-categorizes based on merchant and context | | **Budget Tracking** | Monthly budget alerts and progress visualization | | **Financial Insights** | Pattern analysis integrated into journal Growth Notes | | **Goal Management** | Savings, budget control, habit, and wishlist goals | | **Weekly Reports** | Automated Sunday 9 PM spending recap | | **Query Support** | Real-time natural language financial inquiries | | **Spending Trends** | Multi-month analytical spending visualization | | **Transaction Browser** | Interactive complete transaction history view | ## Workflow As a PhoenixClaw plugin, Ledger hooks into the `post-moment-analysis` phase: 1. **Receive Moments**: Get identified moments from PhoenixClaw Core 2. **Detect Finances**: Scan for expense/income signals in text and media - Text: Semantic patterns (see `references/expense-detection.md`) - Media: Payment screenshots (see `references/payment-screenshot.md`) 3. **Extract Data**: Parse amount, merchant, category, timestamp 4. **Categorize**: Apply rules from `references/merchant-category-map.md` 5. **Deduplicate**: Prevent double-counting same transaction 6. **Store**: Write to `~/PhoenixClaw/Finance/ledger.yaml` 7. **Export**: Generate journal section using `assets/daily-finance-section.md` ## Explicit Triggers While passive by design, users can interact directly: - *"How much did I spend today/this week/this month?"* - *"Show my expense breakdown"* - *"Set my monthly budget to [amount]"* - *"What are my top spending categories?"* - *"Generate financial report for [period]"* - *"Set a savings goal for [amount] by [date]"* - *"Show my spending trends"* - *"Browse all my transactions"* - *"How am I doing on my goals?"* ## Output Structure ``` ~/PhoenixClaw/ ├── Journal/ │ ├── daily/2026-02-02.md # Contains 💰 Finance section │ └── weekly/2026-W05.md # Weekly financial recaps │ └── Finance/ # Ledger-specific directory ├── ledger.yaml # Structured transaction data ├── budget.yaml # Budget configuration ├── goals.yaml # Financial goals tracking ├── transactions.md # Transaction browser view ├── monthly/ │ └── 2026-02.md # Monthly financial reports └── yearly/ └── 2026.md # Annual summaries ``` ## Configuration Ledger-specific settings in `~/.phoenixclaw/config.yaml`: ```yaml plugins: phoenixclaw-ledger: enabled: true default_currency: CNY # or USD, EUR, etc. budget_monthly: 5000 # Monthly budget amount categories_custom: [] # User-defined categories screenshot_confidence: 0.7 # Min confidence for auto-record ``` ## Cron & Scheduled Reports Ledger uses PhoenixClaw Core's cron infrastructure plus additional scheduled tasks: | Task | Schedule | Description | |------|----------|-------------| | **Daily Processing** | 10 PM (via Core) | Extracts transactions, generates daily section | | **Monthly Report** | 1st of month, 8 AM | Comprehensive monthly financial summary | | **Weekly Summary** | Sunday 9 PM (optional) | Weekly spending recap | ### Daily Processing (Automatic) No separate setup required. Ledger hooks into Core's nightly cron: - Core runs at 10 PM → triggers `post-moment-analysis` - Ledger activates, extracts finances, exports to journal ### Monthly Report Setup ```bash openclaw cron add \ --name "PhoenixClaw Ledger monthly report" \ --cron "0 8 1 * *" \ --tz "auto" \ --session isolated \ --message "Generate monthly financial report for the previous month." ``` See `references/cron-setup.md` for full configuration details. ## Documentation Reference ### References (`references/`) - `expense-detection.md`: Semantic patterns for conversation parsing - `payment-screenshot.md`: Screenshot recognition and OCR extraction - `merchant-category-map.md`: Merchant to category mapping rules - `category-rules.md`: Category definitions and hierarchy - `budget-tracking.md`: Budget alerts and progress calculation - `financial-insights.md`: Pattern analysis for Growth Notes - `cron-setup.md`: Scheduled tasks and report automation - `goal-management.md`: Financial goals and progress tracking - `query-patterns.md`: Natural language query templates and logic ### Assets (`assets/`) - `expense-callout.md`: Template for conversation-detected expenses - `receipt-callout.md`: Template for screenshot-detected expenses - `daily-finance-section.md`: Journal integration template - `monthly-report.md`: Monthly summary template - `yearly-report.md`: Annual summary template ---