--- name: billclaw-2d723a2447fd description: This skill should be used when managing financial data, syncing bank transactions via Plaid/GoCardless, fetching bills from Gmail, or exporting to Beancount/Ledger formats. Provides local-first data sovereignty for OpenClaw users. tags: [finance, banking, plaid, gocardless, gmail, beancount, ledger, transactions] --- # BillClaw - Financial Data Sovereignty for OpenClaw Complete financial data management skill for OpenClaw with local-first architecture. Sync bank transactions, fetch bills from email, and export to accounting formats. ## When to Use This Skill Use this skill when: - Syncing bank transactions from Plaid (US/Canada) or GoCardless (Europe) - Fetching and parsing bills from Gmail - Exporting financial data to Beancount or Ledger formats - Managing local transaction storage with caching and indexing - Running financial data operations with full data sovereignty ## Package Information - **Packages**: `@firela/billclaw-core`, `@firela/billclaw-cli`, `@firela/billclaw-openclaw` - **Repository**: https://github.com/fire-la/billclaw - **Version**: 0.0.1 - **License**: MIT ## Installation ### Via npm ```bash # Core package (framework-agnostic) npm install @firela/billclaw-core # CLI application npm install @firela/billclaw-cli # OpenClaw plugin npm install @firela/billclaw-openclaw ``` ### Via pnpm ```bash pnpm add @firela/billclaw-core pnpm add @firela/billclaw-cli pnpm add @firela/billclaw-openclaw ``` ## CLI Usage ### Setup Wizard ```bash billclaw setup ``` Interactive wizard for: - Linking Plaid accounts - Configuring Gmail bill fetching - Setting up local storage path ### Sync Transactions ```bash # Sync all accounts billclaw sync # Sync specific account billclaw sync --account # Sync with date range billclaw sync --from 2024-01-01 --to 2024-12-31 ``` ### Status & Configuration ```bash # View account status billclaw status # List all accounts billclaw config accounts # View storage statistics billclaw status --storage ``` ### Export Data ```bash # Export to Beancount billclaw export --format beancount --output transactions.beancount # Export to Ledger billclaw export --format ledger --output transactions.ledger # Export with date filter billclaw export --from 2024-01-01 --format beancount ``` ## OpenClaw Plugin Usage When installed in OpenClaw, this skill provides: ### Tools - `plaid_sync` - Sync bank transactions from Plaid - `gmail_fetch` - Fetch bills from Gmail - `bill_parse` - Parse bill documents - `conversational_sync` - Natural language sync interface - `conversational_status` - Check sync status - `conversational_help` - Get help with commands ### Commands - `/billclaw-setup` - Configure accounts - `/billclaw-sync` - Sync transactions - `/billclaw-status` - View status - `/billclaw-config` - Manage configuration ### OAuth Providers - Plaid Link integration for bank account linking - Gmail OAuth for bill fetching ## Features ### Data Sources | Source | Description | Regions | |--------|-------------|---------| | **Plaid** | Bank transaction sync | US, Canada | | **GoCardless** | European bank integration | Europe | | **Gmail** | Bill fetching via email | Global | ### Storage Architecture - **Location**: `~/.billclaw/` (configurable) - **Format**: Monthly partitioned JSON files - **Caching**: TTL-based in-memory cache - **Deduplication**: 24-hour window based on transaction ID - **Streaming**: Efficient handling of large datasets ### Export Formats - **Beancount**: Double-entry accounting format - **Ledger**: CLI accounting tool format - **CSV**: Spreadsheet-compatible format ### Security - Platform keychain storage for credentials (keytar) - Audit logging for all credential access - Optional AES-256-GCM encryption - Local-first architecture - your data never leaves your control ## Configuration Configuration is stored in `~/.billclaw/config.yaml`: ```yaml accounts: - id: plaid-checking type: plaid name: "My Checking Account" enabled: true syncFrequency: daily - id: gmail-bills type: gmail name: "Bill Email Fetcher" enabled: true syncFrequency: daily storage: path: "~/.billclaw" format: json sync: defaultFrequency: daily retryOnFailure: true maxRetries: 3 ``` ## Runtime Abstractions The core package is framework-agnostic and uses runtime abstractions: - **Logger**: Abstract logging interface - **ConfigProvider**: Configuration management - **EventEmitter**: Event system for sync operations This allows BillClaw to work across different environments (CLI, OpenClaw plugin, future platforms). ## Event System BillClaw emits events for important operations: - `transaction.added` - New transactions added - `transaction.updated` - Existing transactions updated - `sync.started` - Sync operation started - `sync.completed` - Sync operation completed - `sync.failed` - Sync operation failed - `account.connected` - Account successfully connected - `account.disconnected` - Account disconnected - `account.error` - Account error occurred ## Scripts ### Validate Skill Run validation before publishing: ```bash ./skills/billclaw/scripts/validate-skill.sh skills/billclaw ``` This checks: - SKILL.md format and required fields - File size limits - Directory structure - Description quality ## Troubleshooting ### Issue: Plaid Link fails **Solution**: Ensure Plaid credentials are configured: ```bash billclaw config plaid --client-id --secret ``` ### Issue: Gmail fetch returns no bills **Solution**: Check Gmail filters and sender whitelist: ```bash billclaw config gmail --filters "from:billing@service.com" ``` ### Issue: Export format incorrect **Solution**: Verify account mappings: ```bash billclaw export --format beancount --show-mappings ``` ## Resources - **Documentation**: https://github.com/fire-la/billclaw - **npm packages**: https://www.npmjs.com/org/fire-zu - **Issues**: https://github.com/fire-la/billclaw/issues ## Contributing Contributions are welcome! Please see CONTRIBUTING.md in the repository. ## License MIT License - See LICENSE file for details. ## Changelog ### 0.0.1 (2025-02-07) Initial release: - Plaid integration for US/Canada banks - GoCardless integration for European banks - Gmail bill fetching and parsing - Local token storage with keychain - Beancount and Ledger export - CLI with setup wizard - OpenClaw plugin with tools and commands - GitHub Actions publishing workflow --- Source attribution: kbarbel640-del Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/xbinkai/billclaw/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2026 clawdbot Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: kbarbel640-del Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/xbinkai/billclaw/SKILL.md Attribution basis: Source repository record Fields of work: Finance & Accounting, Operations, Sales Roles: Accountant, Business Development, CFO / FP&A, Financial Analyst, Operations Manager Specialties: API, Database Tools: Gmail, Beancount, Ledger, Plaid Country applicability: Canada, United States Classification basis: Source catalog labels Instruction SHA-256: e2ac84f94201aff0c14d5f0b24e23108c81a6307b691f6fc02d24fb7dead2fbb