Skip to content
SlashClone
DiscoverUse in ClaudeSubmit a link
Sign in
Made by@ledgerly

Expense categorizer

@ledgerly/expense-categorizer

Categorize a bank or card CSV export with a rules file you can edit. Writes a categorized CSV, spend by category and by month, and a review list of unknown merchants with suggested rules. Offline and repeatable.

SkillFinancev1.0.0 (latest)Tested
Use in Claude Save Like Clone Comment
Activity
New: be the first to try it
  1. 1---
  2. 2name: expense-categorizer
  3. 3description: Categorize transactions from a bank or credit card CSV export using a plain rules file the user owns and can edit, then summarize spend by category and month and list unknown merchants for review. Use when the user says "categorize my expenses", "where is our money going", "clean up this bank export", "tag these card transactions", or needs spend by category for a budget, a runway model, or month-end close.
  4. 4license: MIT
  5. 5---
  6. 6
  7. 7# Expense categorizer
  8. 8
  9. 9Rules, 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.
  10. 10
  11. 11## Inputs
  12. 12
  13. 131. **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`.
  14. 142. **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:
  15. 15
  16. 16 ```csv
  17. 17 pattern,category,match,min_amount,max_amount,notes
  18. 18 uber eats,Meals,contains,,,
  19. 19 uber,Travel,contains,0,150,Rides only
  20. 20 ```
  21. 21
  22. 22 `match` is `contains` (default, case-insensitive), `starts_with`, `exact`, or `regex`. **First match wins**, so specific rules go above general ones.
  23. 23
  24. 24Ask 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`.
  25. 25
  26. 26## Steps
  27. 27
  28. 281. Look at the header and five rows. Confirm the account and the date range with the user.
  29. 292. Run:
  30. 30
  31. 31 ```bash
  32. 32 node scripts/categorize.mjs data/bank-2026-10.csv --rules data/expense-rules.csv --out out/expenses
  33. 33 ```
  34. 34
  35. 353. Read `out/expenses-summary.md` and report: total out, total in, share of spend categorized, and the top 5 categories.
  36. 364. **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.
  37. 375. **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.
  38. 386. Hand over: `out/expenses-categorized.csv` (one row per transaction, with the rule that matched) and the summary.
  39. 39
  40. 40## Category set (default)
  41. 41
  42. 42Payroll, 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.
  43. 43
  44. 44## Output template
  45. 45
  46. 46```markdown
  47. 47**October spend: $288,703 out, $202,667 in.** 99.6% categorized by rules.
  48. 48Top categories: Payroll $246,701 (85%), Rent $8,400, Cloud $8,223 ...
  49. 49Needs a decision (4 merchants, $1,119): AMZN MKTP (3 charges, $429), ...
  50. 50```
  51. 51
  52. 52## Guardrails
  53. 53
  54. 54- Never change the source export. New rules go only in `data/expense-rules.csv`, and only after the user confirms them.
  55. 55- 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.
  56. 56- Do not paste full transaction lists into chat. Summarize and point to the files.
  57. 57- If more than 5% of rows are skipped (no date or amount), stop and check the export format with the user.
Sign in to comment on a line