phoenixclaw-ledger

metadata: version: 0.1.0

depends: phoenixclaw protocol_version: 1 min_core_version: 0.0.3 hook_point: post-moment-analysis data_access: - moments - user_config - memory export_to_journal: true

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:

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:

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:

Monthly Report Setup

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

Assets (assets/)

Ledger-specific settings in ~/.phoenixclaw/config.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