billclaw

# 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**: `@fire-zu/billclaw-core`, `@fire-zu/billclaw-cli`, `@fire-zu/billclaw-openclaw` - **Repository**: https://github.com/fire-zu/billclaw - **Version**: 0.0.1 - **License**: MIT ## Installation ### Via npm ```bash # Core package (framework-agnostic) npm install @fire-zu/billclaw-core # CLI application npm install @fire-zu/billclaw-cli # OpenClaw plugin npm install @fire-zu/billclaw-openclaw ``` ### Via pnpm ```bash pnpm add @fire-zu/billclaw-core pnpm add @fire-zu/billclaw-cli pnpm add @fire-zu/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 <account-id> # 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 <id> --secret <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-zu/billclaw - **npm packages**: https://www.npmjs.com/org/fire-zu - **Issues**: https://github.com/fire-zu/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