Billclaw

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.

Security Scan

BillClaw's declared requirements, installation steps, and runtime instructions are coherent with a local-first financial sync/export tool and do not request surprising credentials or privileges.

Purpose & Capability

The skill's name/description (Plaid/Gmail sync, exports, local storage) matches the declared npm packages and optional Connect/CLI components. Requiring Node and providing npm packages for OpenClaw integration is proportionate to the stated purpose.

Instruction Scope

SKILL.md directs the user to install the listed npm packages, configure Plaid/Gmail credentials only when needed, run an interactive setup, and store data under ~/.firela/billclaw or system keychain. It does not instruct broad system scanning, harvest unrelated environment variables, or phone home to unexpected endpoints in the provided content.

Install Mechanism

Installation uses npm packages (@firela/*). npm is a normal distribution mechanism for Node tools but carries standard supply-chain risk (transitive dependencies). There are no downloads from arbitrary URLs, no extracted archives, and the install spec is consistent with the skill's purpose.

Credentials

No environment variables are required at install time. The SKILL.md lists Plaid and Gmail credentials for the features that need them, which is appropriate. There are no unrelated credentials or excessive env var requirements declared.

Persistence & Privilege

always:false and disable-model-invocation:true limit autonomous or always-on behavior. The skill does not request system-wide config changes or access to other skills' secrets in the provided content.

Assessment

This skill appears coherent for local financial syncing: if you plan to use it, review the npm packages' source (the repo links are provided), verify package provenance if that matters to you, and only supply Plaid/Gmail credentials when you enable those features. Because it installs Node packages, consider installing in a controlled environment (container or dedicated machine) if you have strong supply-chain concerns, and monitor network traffic on first run to confirm calls go only to Plaid/Gmail endpoints. The skill's disable-model-invocation setting reduces autonomous risk. If you rely on the optional Connect component (self-hosted OAuth), review its configuration carefully before exposing it to the network.

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
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

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:

# 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:

{
  "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 [e-mail]
• npm packages: https://www.npmjs.com/org/firela