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

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:

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:

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

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