💰 FinTrack AI

AI-powered personal finance tracker that lives in your Discord and Slack.

Log expenses, scan receipts, track budgets, and get spending insights — all through natural language conversation. No app to download, no forms to fill, no learning curve.

Built by Team TensorMinds for the hackathon.

---

Features

• Natural Language Logging — Type "coffee $4.75" or "Uber ride $23" and the AI extracts amount, category, merchant, and date automatically
• Receipt Scanning — Send a photo of any receipt; Claude Vision extracts merchant, line items, total, and date
• Budget Monitoring — Set per-category monthly budgets with custom alert thresholds; get warned before you overspend
• Conversational Queries — "How much did I spend this month?", "Compare Jan vs Feb", "Top 5 categories"
• Bill Splitting — "Split dinner with 3 friends, total was $180" auto-calculates your $45 share
• Multi-Currency — "10 Rs on tea" converts and records with the original currency noted
• Live Dashboard — Real-time web dashboard with charts, budget bars, and transaction history
• Corrections & Refunds — Mistakes create adjustment entries; the ledger is append-only

Architecture

Discord/Slack → OpenClaw Gateway → Claude Sonnet 4 → finance.mjs CLI → CSV/JSON → Dashboard

Layer	Component	Role
Input	Discord DM, Slack DM	User sends messages or receipt photos
Gateway	OpenClaw	Channel plugins, skill routing, session management
AI	Claude Sonnet 4	NLU, intent detection, category inference, receipt OCR
Engine	finance.mjs	Zero-dep Node.js CLI with 8 commands (add, query, budget, export)
Storage	transactions.csv, budgets.json	Append-only local files
Viz	dashboard.html + Chart.js	Live dashboard auto-refreshing every 5 seconds

Project Structure

C:\TensorMinds\
├── README.md                              # This file
├── transactions.csv                       # Append-only transaction ledger
├── budgets.json                           # Budget limits & alert thresholds
├── dashboard-server.mjs                   # HTTP server for dashboard API (port 3333)
├── dashboard.html                         # Live dashboard UI (Chart.js)
├── architecture.html                      # SVG system architecture diagram
├── presentation.html                      # 12-slide hackathon presentation deck
├── project-report.html                    # Full project report with elevator pitch
└── skills/
    └── finance-tracker/
        ├── SKILL.md                       # OpenClaw skill definition & agent instructions
        ├── scripts/
        │   └── finance.mjs               # Core data engine (~580 lines, zero npm deps)
        └── references/
            └── categories.md             # Category taxonomy & keyword mappings

Tech Stack

Component	Technology
AI Reasoning	Claude Sonnet 4 (anthropic/claude-sonnet-4-20250514)
Receipt OCR	Claude Vision
Agent Framework	OpenClaw (multi-channel gateway)
Data Engine	Node.js 22+ (built-in modules only)
Dashboard	Chart.js 4.4, vanilla HTML/CSS/JS
Channels	Discord (Socket), Slack (Socket Mode)
Storage	CSV + JSON (local, append-only)

Zero npm dependencies — finance.mjs uses only node:fs, node:path, and node:crypto.

Quick Start

Prerequisites

• Node.js 22+
• OpenClaw installed (npm install -g openclaw@latest)
• Anthropic API key
• Discord bot token and/or Slack bot + app tokens

1. Start OpenClaw Gateway

openclaw start

2. Start the Dashboard

node dashboard-server.mjs C:\TensorMinds

Dashboard available at http://localhost:3333

3. Start Chatting

Send a DM to the bot on Discord or Slack:

Spent $12.50 on lunch at Chipotle

The AI will log the expense, categorize it, and check your budget automatically.

CLI Commands

The data engine (finance.mjs) supports these commands:

# Initialize data files
node finance.mjs init --data-dir .

# Log an expense
node finance.mjs add --data-dir . --date 2026-02-14 --amount 12.50 \
  --category Food --merchant "Chipotle" --description "Lunch"

# Query spending
node finance.mjs query --data-dir . --period month
node finance.mjs query --data-dir . --top-categories 5 --period month
node finance.mjs query --data-dir . --compare-months 2026-01 2026-02

# Manage budgets
node finance.mjs budget set --data-dir . --category Food --limit 500
node finance.mjs budget list --data-dir .
node finance.mjs budget status --data-dir .
node finance.mjs budget remove --data-dir . --category Food

# Export all transactions
node finance.mjs export --data-dir .

All output is JSON to stdout (except export which outputs raw CSV).

CSV Schema

id,date,amount,category,merchant,description,channel,raw_input

Categories: Food, Transport, Housing, Entertainment, Shopping, Utilities, Health, Other

Presentation Materials

Resource	URL
Live Dashboard	localhost:3333
Architecture Diagram	localhost:3333/architecture.html
Slide Deck (12 slides)	localhost:3333/presentation.html
Full Project Report	localhost:3333/project-report.html

Design Principles

1. Zero External Dependencies — Only Node.js built-in modules
2. Privacy First — All data stays local; never leaves your machine
3. Append-Only Ledger — Transactions are never mutated; corrections create adjustment entries
4. Structured I/O — All CLI output is JSON for reliable AI agent parsing
5. Idempotent Init — Running init multiple times is safe
6. Platform Agnostic — Works on Windows, macOS, Linux

License

Hackathon project by Team TensorMinds.