billclaw

# BillClaw - Financial Data Management for OpenClaw Complete financial data management for OpenClaw with local-first architecture. Sync bank transactions, fetch bills from email, and export to accounting formats. ## Security & Trust **BillClaw is safe, open-source software designed with security-first principles.** ### Verification - **Transparent packages**: All npm packages are open-source and published with provenance - **Auditable code**: Full source available at [GitHub](https://github.com/fire-la/billclaw) - **npm provenance**: Cryptographic proof linking packages to source code - **Local-first**: Your financial data never leaves your machine - **User-controlled credentials**: You provide all API credentials through your own accounts - **System keychain**: Tokens encrypted in your platform's secure keychain - **Explicit invocation**: Requires explicit user action (`disable-model-invocation: true`) See [SECURITY.md](./SECURITY.md) for detailed security architecture and verification steps. ### Addressing Security Concerns | Concern | Explanation | |---------|-------------| | **sets-process-name** | Comes from transitive npm dependencies, not BillClaw code | | **detect-debug-environment** | Common Node.js ecosystem pattern, not malicious | | **API credentials** | Required for functionality; you control them from your accounts | | **External packages** | All packages are open-source with npm provenance | ## Required Credentials **Important**: Credentials are NOT required at install time. Configure them when you're ready to use specific features: | Environment Variable | Purpose | Required For | |---------------------|---------|--------------| | `PLAID_CLIENT_ID` | Plaid API client ID | Plaid bank sync | | `PLAID_SECRET` | Plaid API secret | Plaid bank sync | | `GMAIL_CLIENT_ID` | Gmail OAuth client ID | Gmail bill fetching | | `GMAIL_CLIENT_SECRET` | Gmail OAuth client secret | Gmail bill fetching | **Obtain credentials from:** - **Plaid**: https://dashboard.plaid.com/ - **Gmail**: https://console.cloud.google.com/apis/credentials **Configure via:** 1. Environment variables (recommended) 2. Configuration file (`~/.firela/billclaw/config.json`) 3. OpenClaw config under `skills.entries.billclaw.env` ## Quick Start (OpenClaw) ### 1. Install the Plugin ```bash npm install @firela/billclaw-openclaw ``` The plugin registers these tools and commands with OpenClaw: - **Tools**: `plaid_sync`, `gmail_fetch`, `conversational_sync`, `conversational_status` - **Commands**: `/billclaw-setup`, `/billclaw-sync`, `/billclaw-status`, `/billclaw-config` ### 2. Configure Credentials When you're ready to use a feature, configure the required credentials: ```bash # For Plaid bank sync export PLAID_CLIENT_ID="your_client_id" export PLAID_SECRET="your_secret" # For Gmail bill fetching export GMAIL_CLIENT_ID="your_client_id" export GMAIL_CLIENT_SECRET="your_secret" ``` ### 3. Setup Your Accounts ``` /billclaw-setup ``` The interactive wizard will guide you through: - Connecting bank accounts (Plaid/GoCardless) - Configuring Gmail for bill fetching - Setting local storage location ### 4. Sync Your Data ``` You: Sync my bank transactions for last month OpenClaw: [Uses plaid_sync tool from BillClaw plugin] Synced 127 transactions from checking account ``` Or use the command directly: ``` /billclaw-sync --from 2024-01-01 --to 2024-12-31 ``` ### 5. Export to Accounting Formats ``` /billclaw-export --format beancount --output 2024.beancount ``` ## OpenClaw Integration This skill provides instructions for using BillClaw with OpenClaw. The actual integration is provided by the **@firela/billclaw-openclaw** npm package. ### Available Tools (via Plugin) - `plaid_sync` - Sync bank transactions from Plaid - `gmail_fetch` - Fetch bills from Gmail - `conversational_sync` - Natural language sync interface - `conversational_status` - Check sync status ### Available Commands (via Plugin) - `/billclaw-setup` - Configure accounts - `/billclaw-sync` - Sync transactions - `/billclaw-status` - View status - `/billclaw-config` - Manage configuration ## Additional Components (Optional) ### Standalone CLI For users who prefer a command-line interface, the standalone CLI is available as a separate npm package. See https://github.com/fire-la/billclaw for installation instructions. ### Connect OAuth Server For self-hosted OAuth flows, the Connect server is available as a separate npm package. See https://github.com/fire-la/billclaw for configuration details. ## Data Sources | Source | Description | Regions | |--------|-------------|---------| | **Plaid** | Bank transaction sync | US, Canada | | **GoCardless** | European bank integration | Europe | | **Gmail** | Bill fetching via email | Global | ## Storage - **Location**: `~/.firela/billclaw/` (your home directory) - **Format**: JSON files with monthly partitioning - **Security**: Local-only storage ## Configuration Configuration is stored in `~/.firela/billclaw/config.json`: ```json { "plaid": { "clientId": "your_client_id", "secret": "your_secret", "environment": "sandbox" }, "gmail": { "clientId": "your_gmail_client_id", "clientSecret": "your_gmail_client_secret" } } ``` ## Export Formats ### Beancount ``` 2024/01/15 * "Starbucks" Expenses:Coffee Liabilities:CreditCard:Visa $5.50 ``` ### Ledger ``` 2024/01/15 Starbucks Expenses:Coffee $5.50 Liabilities:Credit Card:Visa ``` ## Getting Help - **Documentation**: https://github.com/fire-la/billclaw - **Issues**: https://github.com/fire-la/billclaw/issues - **Security**: Report security vulnerabilities privately at security@fire-la.dev - **npm packages**: https://www.npmjs.com/org/firela