Finance Skill

Parse and store transactions from bank statements, enable querying and adding personal finance data in JSON format within a local workspace.

Security Scan

The skill's files and runtime instructions are coherent with a local personal-finance tool: it parses statements, stores transactions under ~/.openclaw/workspace/finance, and uses jq/pypdf; it does not request credentials or call external endpoints.

Purpose & Capability

Name/content claim (parse statements, store/query transactions) matches the included scripts, SKILL.md, and README. Required tools (jq, pypdf) are appropriate for JSON manipulation and PDF text extraction. No unrelated credentials, binaries, or services are requested.

Instruction Scope

Runtime instructions operate on local files under ~/.openclaw/workspace/finance and call only local scripts and pypdf; they instruct verification before import. There are no instructions to read system config outside the workspace or to transmit data to remote endpoints.

Install Mechanism

No install spec (instruction-only) and included scripts are simple shell + jq; dependencies are standard (jq via apt/brew, pypdf via pip). No downloads from untrusted URLs or archive extraction.

Credentials

The skill declares no environment variables or credentials and none are required by the scripts. Future Plaid integration is only mentioned as a roadmap item and is not implemented.

Persistence & Privilege

always:false and user-invocable; the skill only writes to its own workspace (~/.openclaw/workspace/finance) and does not modify other skills or system-wide settings.

Assessment

This skill appears internally consistent and stores data locally, but review before installing: 1) Ensure you trust the skill source since it will store sensitive financial data under ~/.openclaw/workspace/finance. 2) The scripts expect valid JSON input and rely on jq/pypdf—install those from your package manager. 3) There are minor implementation bugs (e.g., use of 'fabs' in jq output may error depending on your jq version); test on non-sensitive data first. 4) If Plaid or any network sync is later added, expect OAuth credentials and network access—review that change carefully. 5) Back up and encrypt the workspace if you store real financial statements.

Personal finance memory layer. Parse statements, store transactions, query spending.

Data Location

• Transactions: ~/.openclaw/workspace/finance/transactions.json
• Raw statements: ~/.openclaw/workspace/finance/statements/

Storage convention: OpenClaw workspace (~/.openclaw/workspace/) is the standard location for persistent user data. This matches where session-memory and other hooks store agent data. Credentials/config would go in ~/.config/finance/ if needed.

Tools

1. Parse Statement

When user shares a statement (image or PDF):

⚠️ IMPORTANT: Telegram/channel previews truncate PDFs! Always extract with pypdf first to get ALL pages:

python3 -c "
import pypdf
reader = pypdf.PdfReader('/path/to/statement.pdf')
for i, page in enumerate(reader.pages):
    print(f'=== PAGE {i+1} ===')
    print(page.extract_text())
"

Then parse the full text output:

1. Extract transactions from ALL pages
2. Return JSON array: [{date, merchant, amount, category}, ...]
3. Run scripts/add-transactions.sh to append to store
4. Verify total matches statement (sum of expenses should equal "Total purchases")

Extraction format:

Each transaction: {"date": "YYYY-MM-DD", "merchant": "name", "amount": -XX.XX, "category": "food|transport|shopping|bills|entertainment|health|travel|other"}
Negative = expense, positive = income/refund.

Categories:

• food: restaurants, groceries, coffee, fast food
• transport: Waymo, Uber, gas, public transit
• shopping: retail, online purchases
• bills: utilities, subscriptions
• entertainment: movies, concerts, theme parks
• health: pharmacy, doctors
• travel: hotels, flights

2. Query Transactions

User asks about spending → read transactions.json → filter/aggregate → answer

Example queries:

• "How much did I spend last month?" → sum all negative amounts in date range
• "What did I spend on food?" → filter by category
• "Show my biggest expenses" → sort by amount

3. Add Manual Transaction

User says "I spent $X at Y" → append to transactions.json

File Format

{
  "transactions": [
    {
      "id": "uuid",
      "date": "2026-02-01",
      "merchant": "Whole Foods",
      "amount": -87.32,
      "category": "food",
      "source": "statement-2026-01.pdf",
      "added": "2026-02-09T19:48:00Z"
    }
  ],
  "accounts": [
    {
      "id": "uuid",
      "name": "Coinbase Card",
      "type": "credit",
      "lastUpdated": "2026-02-09T19:48:00Z"
    }
  ]
}

Usage Flow

1. User: shares statement image
2. Agent: extracts transactions via vision, confirms count
3. Agent: runs add script to store
4. User: "how much did I spend on food?"
5. Agent: reads store, filters, answers

Dependencies

• jq — for JSON transaction storage and querying (apt install jq / brew install jq)
• pypdf — for full PDF text extraction (pip3 install pypdf)

Lessons Learned

• Telegram truncates PDF previews — always use pypdf to get all pages
• Verify totals — sum extracted expenses and compare to statement total before importing
• Coinbase Card — no Plaid support, statement upload only

Future: Plaid Integration

• Add finance_connect tool for Plaid OAuth flow
• Auto-sync transactions from connected banks
• Same query interface, different data source