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
• 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 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
INLINECODE1	Plaid API client ID	Plaid bank sync
INLINECODE2

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. 1. Environment variables (recommended)
2. Configuration file (~/.firela/billclaw/config.json)
3. OpenClaw config under INLINECODE6

Quick Start (OpenClaw)

1. Install the Plugin

CODEBLOCK0

The plugin registers these tools and commands with OpenClaw:

• - Tools: plaid_sync, gmail_fetch, conversational_sync, INLINECODE10
• Commands: /billclaw-setup, /billclaw-sync, /billclaw-status, INLINECODE14

2. Configure Credentials

When you're ready to use a feature, configure the required credentials:

CODEBLOCK1

3. Setup Your Accounts

CODEBLOCK2

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

CODEBLOCK3

Or use the command directly:
CODEBLOCK4

5. Export to Accounting Formats

CODEBLOCK5

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
• INLINECODE16 - Fetch bills from Gmail
• INLINECODE17 - Natural language sync interface
• INLINECODE18 - Check sync status

Available Commands (via Plugin)

• - /billclaw-setup - Configure accounts
• INLINECODE20 - Sync transactions
• INLINECODE21 - View status
• INLINECODE22 - 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:

CODEBLOCK6

Export Formats

Beancount

CODEBLOCK7

Ledger

CODEBLOCK8

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