| name | heath-ledger |
| description | AI bookkeeping agent for Mercury bank accounts. Pulls transactions, categorizes them (rule-based + AI), and generates Excel workbooks with P&L, Balance Sheet, Cash Flow, and transaction detail. Use when the user wants to do bookkeeping, generate financial statements, categorize bank transactions, connect Mercury, or produce monthly/quarterly/annual books. Triggers on: bookkeeping, P&L, profit and loss, balance sheet, cash flow, financial statements, Mercury bank, categorize transactions, generate books, monthly close. |
Heath Ledger
AI bookkeeping skill for Mercury bank accounts.
Quick Start
scripts/init_db.mjs — creates DB + seeds ~90 universal vendor→category rulesscripts/connect_mercury.sh <MERCURY_API_TOKEN> [entity_name] — discovers accounts- (Optional)
scripts/connect_stripe.sh <entity_id> <stripe_api_key> — connect Stripe for exact revenue + fees
- (If Stripe connected)
scripts/pull_stripe_revenue.sh <entity_id> <start_date> <end_date> — pull monthly revenue data
scripts/pull_transactions.sh <entity_id> <start_date> <end_date>scripts/categorize.sh <entity_id> — rule-based first, AI for unknowns- Review ambiguous items, correct with
scripts/set_category.sh
scripts/generate_books.sh <entity_id> <start_date> <end_date> [output_path]
Setup Flow
Mercury API Key (Required)
Get from Mercury Dashboard → Settings → API Tokens. The token gives read-only access to transactions.
Stripe API Key (Optional but Recommended)
Without Stripe API: Mercury shows net Stripe deposits (revenue minus fees). The system estimates gross revenue using a configurable fee rate (default 2.3% + $0.30).
With Stripe API: You get exact gross revenue, exact fees, and proper refund tracking. Always prefer this when available.
To connect: scripts/connect_stripe.sh <entity_id> <stripe_api_key>
Then pull data: scripts/pull_stripe_revenue.sh <entity_id> <start_date> <end_date>
The P&L generator automatically uses Stripe data when available, falling back to Mercury estimates otherwise.
Entity Settings
Configure per-entity via the entity_settings table:
| Setting | Default | Description |
|---|
accounting_basis | accrual | accrual or cash — cash basis uses posted dates only |
month_offset | 1 | Fiscal year month offset (1 = calendar year) |
stripe_fee_rate | 0.023 | Stripe percentage fee for gross-up calculation |
stripe_fee_fixed | 0.30 | Stripe fixed fee per transaction |
amortization_monthly | null | Monthly amortization amount for acquired assets |
Workflow
- Connect Mercury —
scripts/connect_mercury.sh <token> [name] discovers accounts, creates entity
- Pull transactions —
scripts/pull_transactions.sh <entity_id> <start_date> <end_date>
- Categorize —
scripts/categorize.sh <entity_id> [max_transactions] — rule-based first, then AI for unknowns
- Review ambiguous — Script outputs low-confidence items. Ask user, then update with
scripts/set_category.sh <transaction_id> <category> [subcategory]
- Generate books —
scripts/generate_books.sh <entity_id> <start_date> <end_date> [output_path]
Scripts Reference
All scripts are in scripts/. Run with bash or node. Database is SQLite at data/heath.db.
| Script | Purpose |
|---|
init_db.mjs | Create/migrate SQLite database + seed rules |
connect_mercury.sh | Connect Mercury API, discover accounts |
pull_transactions.sh | Pull transactions for date range |
categorize.sh | Categorize transactions (rules + AI) |
set_category.sh | Manually set category for a transaction |
add_rule.sh | Add/update a categorization rule |
generate_books.sh | Generate Excel workbook |
list_entities.sh | List all entities |
connect_stripe.sh | Connect Stripe API to an entity |
pull_stripe_revenue.sh | Pull Stripe balance transactions by month |
status.sh | Show entity status (accounts, tx counts) |
Chart of Accounts
See references/chart-of-accounts.md for the full chart with P&L sections and cash flow classifications.
Learning & Compounding System
Heath Ledger gets smarter over time through a layered rule system:
Rule Hierarchy
- Entity-specific rules (highest priority) — per-company overrides
- Global rules (
entity_id = NULL) — apply to all entities
- Seed rules — universal vendor mappings shipped with the skill
- AI categorization — used when no rule matches
How Learning Works
- Every manual correction creates or updates a categorization rule
- Rules track
usage_count — heavily-used rules are more reliable
source field tracks provenance: seed, ai, human, manual- Human-confirmed rules get
confidence: 0.95-1.0
- AI-generated rules start at
0.85 and can be promoted
- Entity-specific rules can be promoted to global when they prove universal
The Compounding Effect
After categorizing ~5,000 transactions across 2 entities, the system now auto-categorizes ~95% of transactions without AI. Each new entity benefits from all previous learnings.
Known Limitations
Stripe Net vs Gross (Without Stripe API)
Mercury deposits from Stripe are net amounts (revenue minus ~2.9% + $0.30 fees). Without the Stripe API:
- We estimate gross revenue using configurable fee rates
- This creates "synthetic" Stripe Fee entries
- Accuracy depends on your actual Stripe fee rate (varies by plan, card type, international)
- Solution: Connect Stripe API for exact numbers
Deel Fee Splitting
Deel combines platform fees and contractor payroll in one transaction stream. Pattern:
- Small fixed amounts (~$2-5) → Deel Platform Fee → categorize as "Software expenses"
- Larger variable amounts → Contractor Payroll → categorize as "Wages & Salaries"
- The system learns this pattern but may need initial human guidance
Mercury API Limitations
- Only returns posted transactions (not pending)
- Some counterparty names are truncated or normalized differently
- Wire descriptions may include reference numbers that create duplicate rules
Multi-Currency
- Wise transfers create both a debit (USD) and may show FX fees separately
- International wire fees from Mercury appear as separate line items
- FX gains/losses are not tracked (would need multi-currency ledger)
AI Categorization
The categorize.sh script calls the host agent's model via stdin/stdout JSON protocol. It sends transaction batches and expects category assignments back. The script writes a prompt to stdout that the agent should process and return results for.
When AI confidence < 0.85, transactions are flagged as ambiguous for user review.
Key Details
- Cash or accrual basis — configurable per entity
- Multiple entities supported — each with own connections and rules
- Rules persist — categorization rules saved to SQLite, reused across runs
- Seed rules — ~90 universal vendor mappings loaded on init
- Excel output — 4-tab workbook: P&L, Balance Sheet, Cash Flow, Transaction Detail
