Expense categorizer

Expense categorizer

Rules, not guesses. Every transaction gets a category from a rules file the user can read and edit, so the same export always gives the same answer, and the rules get better each month.

Inputs

1. Transactions CSV in data/ (for example data/bank-2026-10.csv). The script finds the columns by common names: date (Date, Posted Date, Transaction Date), description (Description, Merchant, Payee, Name, Memo), and either Amount or Debit and Credit.

2. Rules file at data/expense-rules.csv. If the user has none, copy examples/rules.csv there as a starting point and tell them. Columns:

   pattern,category,match,min_amount,max_amount,notes
   uber eats,Meals,contains,,,
   uber,Travel,contains,0,150,Rides only

   match is contains (default, case-insensitive), starts_with, exact, or regex. First match wins, so specific rules go above general ones.

Ask which sign means money out if the export is unusual. By default the script decides: if most amounts are negative, negative is spend (typical for bank exports); otherwise positive is spend (typical for card exports). Override with --spend-sign negative or --spend-sign positive.

Steps

1. Look at the header and five rows. Confirm the account and the date range with the user.

2. Run:

   node scripts/categorize.mjs data/bank-2026-10.csv --rules data/expense-rules.csv --out out/expenses

3. Read out/expenses-summary.md and report: total out, total in, share of spend categorized, and the top 5 categories.
4. Review unknowns with the user. out/expenses-unknowns.csv groups uncategorized transactions by merchant, biggest first, with a suggested rule line. Propose a category for each of the top ones in a short table and ask the user to confirm or correct.
5. Add confirmed rules to data/expense-rules.csv (put specific ones above general ones), then rerun. Repeat until at least 95% of spend is categorized or the user is happy.
6. Hand over: out/expenses-categorized.csv (one row per transaction, with the rule that matched) and the summary.

Category set (default)

Payroll, Contractors, Cloud and hosting, AI and model APIs, Software, Marketing, Rent and office, Travel, Meals, Legal, Accounting, Insurance, Taxes, Equipment, Bank fees, Revenue, Transfers. Use the user's chart of accounts instead if they have one; ask once.

Output template

**October spend: $288,703 out, $202,667 in.** 99.6% categorized by rules.
Top categories: Payroll $246,701 (85%), Rent $8,400, Cloud $8,223 ...
Needs a decision (4 merchants, $1,119): AMZN MKTP (3 charges, $429), ...

Guardrails

• Never change the source export. New rules go only in data/expense-rules.csv, and only after the user confirms them.
• Transfers between the company's own accounts and credit card payments are not spend. Add rules that put them in Transfers so they do not double count.
• Do not paste full transaction lists into chat. Summarize and point to the files.
• If more than 5% of rows are skipped (no date or amount), stop and check the export format with the user.

Expense categorizer

Categorizes a bank or card CSV with a rules file you own, then shows spend by category and month. Anything it cannot place goes on a short review list, with a suggested rule so next month is automatic.

Who it is for: founders and ops or finance folks who do the books from bank exports, prep for month-end close, or need real burn numbers for a budget or runway model.

Example

Input: examples/transactions.csv (38 bank transactions over two months) and examples/rules.csv (about 40 starter rules).

Output (out/expenses-summary.md):

38 transactions. Money out $288,703, money in $202,667. 99.6% of spend matched a rule.

| Category | Total | Share |
| Payroll | $246,701 | 85.5% |
| Rent and office | $8,400 | 2.9% |
...
## Needs review
| AMZN MKTP US | out | 3 | $428.57 | AMZN MKTP US*2K4LL | `amzn mktp us,<category>,contains` |

Plus out/expenses-categorized.csv with the category and matching rule for every row.

What it can access

• Runs node scripts/categorize.mjs (Node built-ins only).
• Reads exports in data/. Writes data/expense-rules.csv (only rules you confirm) and out/expenses*.
• No network, no bank logins, no API keys.

Setup

Export transactions from your bank or card as CSV into data/, then ask Claude to categorize them. It starts you off with the example rules.