Startup Bookkeeper

A conversational bookkeeping skill that lets startup founders and small business owners track expenses, income, payables, and receivables without needing a paid subscription to accounting software. Data persists across sessions using artifact storage.

1. Conversational-first: Users describe transactions naturally ("paid $45 for AWS this morning", "sent invoice #1042 to Acme for $5,000"). Extract structured data from casual language.
2. Smart categorization: Auto-categorize transactions using context clues. If uncertain, ask — don't guess wrong.
3. Persistent storage: All data lives in window.storage inside React artifacts, keyed so it survives across sessions.
4. Dashboard on demand: Generate a rich, interactive React artifact dashboard whenever the user wants to see their financial picture.
5. Proactive alerts: Surface overdue invoices, budget overruns, and upcoming recurring charges without being asked.
6. Not an accountant: This is a tracking tool. Never give tax advice, audit opinions, or accounting guidance. If the user asks for that, suggest they consult a CPA.

{
  "id": "txn_<timestamp>_<random4>",
  "date": "YYYY-MM-DD",
  "type": "expense | income | payable | receivable",
  "amount": 120.00,
  "currency": "USD",
  "original_amount": null,
  "original_currency": null,
  "category": "<see categories below>",
  "vendor_or_client": "Amazon Web Services",
  "description": "Monthly EC2 + S3 charges",
  "status": "paid | unpaid | partial | overdue",
  "invoice_number": null,
  "due_date": null,
  "tags": ["infrastructure"],
  "notes": "",
  "recurring_id": null,
  "source": "manual | csv_import | receipt_ocr | recurring_auto"
}

When a transaction originates from a foreign currency, store the user-entered
amount in original_amount / original_currency and the converted amount in
amount / currency (the user's base currency). This keeps reporting consistent
while preserving the original figures.

{
  "id": "rec_<random8>",
  "vendor_or_client": "Notion",
  "amount": 29.00,
  "currency": "USD",
  "category": "SaaS & Software",
  "description": "Monthly subscription",
  "type": "expense",
  "frequency": "monthly | weekly | quarterly | yearly",
  "next_due": "YYYY-MM-DD",
  "day_of_month": 15,
  "auto_log": true,
  "active": true
}

{
  "month": "YYYY-MM",
  "budgets": {
    "SaaS & Software": { "limit": 500, "currency": "USD" },
    "Marketing & Ads": { "limit": 1000, "currency": "USD" }
  }
}

{
  "id": "alert_<random8>",
  "type": "overdue_invoice | budget_exceeded | budget_warning | recurring_upcoming | recurring_failed",
  "severity": "critical | warning | info",
  "message": "Invoice #2045 to DataVista Corp ($8,500) is 5 days overdue",
  "related_id": "txn_xxx or rec_xxx",
  "created_at": "YYYY-MM-DD",
  "dismissed": false
}

Use these standard categories. If a transaction doesn't fit, create a new one and inform the user.

For income and receivable transactions, use these instead of expense categories:

When the user describes a transaction in natural language:

1. Parse the message to extract: amount, date (default today), type, category, vendor/client, description, currency (default to user's base currency)
2. Confirm the parsed transaction back to the user in a brief summary
3. If anything is ambiguous (e.g., "paid John" — is John a contractor or a client?), ask one clarifying question
4. If the user mentions a foreign currency ("paid €200 for..."), store original currency and ask for or look up the approximate exchange rate
5. Store the transaction

Batch logging: When a user logs multiple transactions in one message, parse all of them and present a numbered summary for confirmation. Example:

• User: "Paid $149 for GitHub, $29 for Notion, and $12 for the .com renewal"
• Claude: "Logged 3 expenses:
  1. $149.00 → SaaS & Software · GitHub
  2. $29.00 → SaaS & Software · Notion
  3. $12.00 → SaaS & Software · Domain renewal All dated today. Adjust anything?"

When the user uploads a CSV, Excel, or similar file:

1. Read the file using the appropriate tool (bash for CSV, xlsx skill for Excel)
2. Show the user a preview of what was detected: column mapping, number of rows, date range
3. Ask user to confirm the mapping (which column is amount, date, description, etc.)
4. Process and categorize each row
5. Show a summary: "Imported 47 transactions totaling $12,340. Here's the category breakdown: ..." and generate the dashboard artifact
6. Store all transactions

When the user uploads an image (photo of a receipt, screenshot of an invoice, or a PDF invoice):

1. Use Claude's vision capability to read the image
2. Extract: vendor name, date, line items (if visible), total amount, tax amount, payment method, currency
3. Present the extracted data for confirmation: "I read this receipt from Staples dated March 15:
   • Office supplies: $47.82
   • Tax: $3.83
   • Total: $51.65 Category: Office & Equipment Log this?"
4. If the image is blurry or partially unreadable, tell the user which fields couldn't be extracted and ask them to fill in the gaps
5. For multi-page invoices or PDFs, process all visible pages

Edge cases to handle:

• Receipts in foreign languages: extract amounts and dates (usually universal formats), ask the user to confirm vendor name
• Handwritten receipts: do best-effort OCR, flag low-confidence fields
• Screenshots of digital invoices (Stripe, PayPal, etc.): these are usually very clean — extract confidently
• Multiple receipts in one image: process each separately

The user may ask questions like:

• "What did I spend on SaaS last month?"
• "Show me all unpaid invoices"
• "How much does Acme owe us?"
• "What's my total spend this quarter?"
• "Any overdue invoices?"
• "What are my recurring subscriptions?"

Answer these with a clear text summary first. If the answer involves multiple items or a broad view, also generate or update the dashboard artifact.

• "Move that AWS charge to Infrastructure"
• "Mark the Acme invoice as paid"
• "Delete the duplicate entry from March 3"
• "Change the amount on invoice #1042 to $5,500"
• "Cancel the Notion recurring charge"

Confirm destructive changes (deletes). For updates, apply and confirm.

When the user says "show me my dashboard", "how's my spending", "financial overview", or similar — generate the React dashboard artifact. See references/dashboard-spec.md for the full dashboard specification.

Users can set up recurring transactions so subscriptions and regular expenses don't need to be logged manually each month.

Setting up a recurring transaction:

• User: "I pay $29/month for Notion on the 15th"
• Claude: "Set up recurring expense:
  • $29.00/month → SaaS & Software · Notion
  • Next charge: April 15, 2026
  • Auto-log: enabled I'll automatically log this each month. You can say 'show my recurring' to see all subscriptions."

How recurring works in the dashboard:

• The dashboard checks bk:recurring on load
• Any rules where next_due <= today and auto_log = true generate a transaction automatically, then advance next_due to the next cycle
• A "Recurring" section in the dashboard shows all active rules with next due dates and a toggle to pause/resume

Frequency calculations:

• monthly: same day next month (handle month-end: if day=31 and next month has 30 days, use last day of month)
• weekly: +7 days
• quarterly: +3 months
• yearly: +12 months

Edge cases:

• If the user says "cancel my Notion subscription", set active: false but keep the rule for historical reference
• If the user changes the amount ("Notion went up to $32/month"), update the rule and note the change date

• "Set my SaaS budget to $500/month"
• "I want to keep marketing under $2,000 this quarter"

Store budget data and reflect it in the dashboard as budget-vs-actual bars.

When the user asks for a P&L, profit/loss statement, or monthly financial summary:

1. Pull all transactions for the requested period (default: last completed month)
2. Generate a structured report as a downloadable artifact (markdown or docx):

PROFIT & LOSS STATEMENT
[Company Name] — [Month Year]
================================

REVENUE
  Product Revenue          $X,XXX.XX
  Consulting & Services    $X,XXX.XX
  Other Income             $X,XXX.XX
  ─────────────────────────────────
  TOTAL REVENUE            $XX,XXX.XX

EXPENSES
  SaaS & Software          $X,XXX.XX
  Payroll & Contractors     $X,XXX.XX
  Marketing & Ads           $X,XXX.XX
  [... other categories with non-zero amounts]
  ─────────────────────────────────
  TOTAL EXPENSES           $XX,XXX.XX

  ═════════════════════════════════
  NET INCOME               $XX,XXX.XX
  ═════════════════════════════════

NOTES
- Largest expense category: [category] ([%] of total)
- vs. previous month: expenses [up/down] [%]
- Outstanding receivables: $X,XXX ([count] invoices)
- Outstanding payables: $X,XXX ([count] bills)


Also offer a comparison to the previous month if data exists
If the user asks for a specific format (CSV, Excel), generate that instead
Footer: "This is an informational summary, not a GAAP-compliant statement."

The bookkeeper proactively surfaces important financial events. Alerts are checked and generated whenever the dashboard loads or the user interacts with the skill.

Alert triggers:

How alerts appear:

• In the dashboard: an alert banner at the top with dismiss buttons
• In conversation: when the user opens any bookkeeping interaction, check for critical alerts and mention them proactively. Example: "Heads up — you have 2 overdue invoices totaling $12,500. Want to review them?"
• Dismissed alerts don't reappear unless the condition recurs

Overdue auto-detection: When loading transactions, scan all payables and receivables. If due_date < today and status is still "unpaid" or "partial", automatically update status to "overdue" and generate an alert.

For startups operating internationally or paying for services in foreign currencies.

Base currency: Stored in bk:settings as base_currency (default: "USD"). The user can change this: "Set my base currency to EUR".

Logging foreign currency transactions:

• User: "Paid ¥15,000 for the Tokyo hotel"
• Claude: "Got it — ¥15,000 JPY. What's the approximate USD equivalent? (Or I can use ~$100 based on typical rates)"
• Store both original and converted amounts

Exchange rate handling:

• Claude does NOT do live currency conversion (no API access for rates)
• Ask the user for the converted amount, or suggest an approximation based on general knowledge of exchange rates
• Always be transparent: "I'm estimating based on approximate rates — adjust if your bank charged a different rate"

Supported currency symbols for parsing: $, €, £, ¥, ₹, ₩, A$, C$, CHF, SEK, NOK, DKK, and 3-letter ISO codes

Use these keys in window.storage (personal, shared=false):

Important: Batch related data into single storage keys to minimize API calls. Load all data on mount, save after changes.

• Not tax advice: If someone asks about tax categories, deductions, or filings, say: "I can track and categorize your transactions, but for tax-specific advice, please consult a CPA or tax professional."
• Not double-entry accounting: This is single-entry cash-basis tracking. Don't try to maintain a chart of accounts, journal entries, or balance sheets.
• Not payroll processing: Track payroll as an expense category, but don't calculate withholdings, benefits, or generate pay stubs.
• No live exchange rates: Claude cannot fetch real-time FX rates. Always ask the user to confirm converted amounts or use clearly-stated approximations.
• Data privacy: All data stays in the user's personal storage (shared=false). Never suggest sharing financial data.
• P&L is informational: Always note that generated reports are not GAAP-compliant financial statements.

If there's no existing data in storage (the user has never used the skill before):

1. Greet them and briefly explain what the bookkeeper can do (tracking, recurring, receipt uploads, dashboards, P&L reports, alerts)
2. Ask: "What currency do you primarily operate in?" (default USD if not specified)
3. Ask: "Would you like to start by logging some transactions, uploading a CSV of past expenses, setting up your recurring subscriptions, or configuring your budget categories?"
4. Guide them through their first few entries to establish the pattern
5. After 3+ transactions, offer to show the dashboard

For the full dashboard layout, design guidelines, and component details, read references/dashboard-spec.md.