Hearth

A personal finance companion that listens, learns, and organizes your spend exactly how you see it.

Comment

Inspiration

Hearth grew from a frustration with existing budgeting tools: they can show where money went, but they rarely let people define spending in the way they actually think about it. Whether you want to bundle home and auto costs into a single "fixed" bucket, you can. And if the app misinterprets a transaction, there's no tedious fixing line by line; you just tell Hearth what you meant, and it learns your preference for the future. The current MVP introduces the core conversational agent engine, supported by the underlying statement-import, rule, and categorization systems; expanding this into richer, fully agent-driven workflows is a planned extension.

What it does

1. Conversational Financial Assistant

Hearth puts an AI companion at the center of your workspace. Instead of navigating complex menus or manually tweaking spreadsheets, you can simply chat with your assistant to summarize spending, inspect specific reports, or search through past transactions naturally.

2. Smart, Human-in-the-Loop Categorization

Hearth respects your time and your existing habits. Known merchants are categorized instantly using your custom household rules. When uncertain transactions pop up, Hearth presents them for a quick bulk review—your confirmations instantly turn into reusable rules for future imports.

3. Seamless Statement Processing

Simply drop in a bank statement (such as a Citi PDF), and Hearth extracts the transactions, identifies the statement month, and compiles everything into a clean spending report. Multiple statements can easily be combined into a single household overview.

Supporting Features

  • Custom Expense Taxonomies: Create and manage personalized household categories by taking to your AI companion or through a simple API.
  • Granular Financial Insights: View high-level category totals down to itemized transaction details.
  • Instant Merchant Recategorization: Update matching merchant transactions across an entire report in one click while automatically saving a rule for the future.
  • Duplicate-Import Protection: Prevents accidental double-counting when uploading multiple statements.
  • Per-User Isolation & Security: Secure sign-in ensures your household financial data remains private and strictly isolated.

How we built it

Hearth is a full-stack household finance tracker built around an assistant-first workflow. The frontend is built with React, Vite, and Recharts. The backend uses Node.js and Express, with Supabase for authentication, Postgres data storage, row-level security, and private statement storage.

The app flow is as follow:

  • Users sign in
  • Upload a Citi statement PDF
  • Heard parses the transactions ignoring card payments and credits/refunds as negative spend
  • If there are household rules define apply them to the parsed transactions.
  • For new transactions, the app uses GPT-5.6 terra to determine which pre-defined category the transactions falls under. If the AI is not able to make the categorization with at least a 0.85% confidence it will push the transactions to a queue for user review.
  • The users will use the assistant UI to resolve the transactions either by accepting the category choice made by AI, choosing a different category or defining a new one.
  • Once the report is displayed on the dashboard the user can use the assistant to gather insights on that report. The assistant flow is powered by GPT 5.6 with server-owned tools to answer report questions such as:
    • What is my dining spend?
    • What is my shopping and dining spend between mar 1 - mar 18?
    • Which category was my highest/lowest spend in?
    • Can you create a new category called "Kids camps"

The model can request report-scoped tools, but it cannot access the database directly or select a different user’s report. The server executes validated tool calls and returns the verified results for the assistant to explain.

I used Codex throughout development to help shape the product MVP and architecture, implement and review features, generate synthetic statement fixtures, diagnose parser edge cases, write and run test and visual-review loops. Product decisions—including the household-category model, review workflow, privacy boundaries, app UI screens and flow, assistant-led user experience and testing the backend and frontend—were made by the developer.

The current MVP supports statement imports, duplicate protection, custom categories, merchant rules, AI-assisted categorization review, transaction editing, report history, and conversational report imports and exploration.

Challenges we ran into

  • Reviewing AI-accelerated development: Codex reduced much of the implementation workload, but it also meant I needed to stay closely involved in reviewing the growing codebase. Manual testing was important for building confidence that the user flows worked as intended, especially after changes crossed frontend, backend, and database boundaries.

  • Making the statement parser resilient: Parsing Citi PDFs required several iterations. Real statements introduced layout variations, multi-line merchant names, and incomplete transaction-date fields that were not obvious from the initial synthetic fixtures.

  • Handling legitimate duplicate transactions: Duplicate detection had an important edge case: one statement could contain multiple transactions with the same merchant, date, and amount. A simple fingerprint would collapse valid purchases. Hearth now keeps repeated same-day transactions distinct while still preventing the exact same statement file from being imported twice.

  • Managing non-deterministic assistant behavior: The assistant relies on an LLM, so small changes in a prompt or in how a user asks a question can lead to different responses. I reduced that variability with constrained tools, clear instructions, structured inputs, and server-side validation, but improving consistency and broader conversational understanding remains an area for future work.

Accomplishments that we're proud of

  • Conversational agent engine
  • Better control over merchant categorization
  • Workable MVP

What we learned

I learned that AI produces better results when it has clear boundaries and concrete expectations to work within. Building Hearth took me from an initial idea to a working MVP and taught me how to prioritize features, refine the interaction design, and iterate on UI screens without losing sight of the core user workflow. I also learned not to blindly trust AI-generated output: I tested both the backend and frontend, used real and synthetic statement data, and iterated whenever the product exposed an edge case. Codex made this process more efficient through an iterative build-and-review loop—plan, implement, test, review, and refine. Finally, I learned how AI assistants can safely work with product data through tool calling: the model requests limited, server-owned tools, while the application validates the request, retrieves only approved data, and returns verified results for the assistant to explain.

What's next for Hearth

  • Agent-Driven Workflows — Expand the assistant beyond answering questions, putting it at the forefront to actively execute complex financial tasks and workflows just by telling it what to do.
  • Voice conversations with Hearth — let users ask and refine finance questions naturally by voice.
  • Richer multi-month assistant insights — reliably explain spending spikes, overall trends, and category trends across reports.
  • Clear Financial Summaries - Get a clean overview of your household spending consolidated into monthly reports.
  • One-Click Bulk Edit Workflow — effortlessly update multiple transactions and bulk save your changes in one go.
  • Broader statement support — extend beyond Citi's initial text-based PDF format to additional banks and statement layouts.

Codex session ID

019f6d12-4b51-7042-8d4d-a90a32b2db0d

Built With

Share this project:

Updates