Squirrel

Never let a voucher expire unnoticed. Squirrel reviews your inbox and card perks for the vouchers, memberships and card perks in and reminds you before they run out.

Comment

Inspiration

One day, my mom was complaining about forgetting to redeem airline miles and restaurant vouchers, sometimes not knowing she even had them. I realised that I too had the same issue. That's the problem I wanted to solve with my project. People lose money on benefits they already have. A birthday voucher, a streaming credit on a credit card, a free gym month or a pile of airline miles each come with an expiry date, and those dates are spread across hundreds of emails, apps and card terms. Nobody keeps a list, so benefits expire unnoticed.

The money is real and already paid for: a premium card's annual fee only makes sense if its monthly and yearly credits get used, and unused vouchers and points are simply lost. The information is already sitting in your inbox. It just needs reading and organising.

What it does

Squirrel builds one list of everything you hold, with expiry dates, from three sources:

  1. Your inbox. Connect Gmail, Outlook or any IMAP mailbox, read-only. Squirrel finds likely benefit emails, skips obvious marketing, and uses an AI model to pull out each benefit: name, provider, value, expiry date, voucher code and terms.
  2. Your credit cards. Pick your cards from a list of 25 US and Singapore cards. Squirrel adds each card's recurring credits and works out when they reset (monthly, quarterly, half-yearly, calendar-year or card anniversary). No card numbers or bank connection needed.
  3. Benefits you add by hand.

From that list, Squirrel:

  • shows what expires soonest on a dashboard,
  • emails you a reminder before each benefit expires (1 week by default, adjustable per benefit),
  • writes an AI weekly digest on request, ranking what needs attention,
  • answers questions like "what can I use for dinner this week?" with an assistant that only uses your own records,
  • sends anything the AI isn't sure about to a review queue, showing the email's own words so you can confirm or fix it.

It also detects 13 hotel and airline loyalty programs from who emails you (no AI), scans QR codes and barcodes with your camera to match them to saved vouchers, and works in light and dark mode on phones.

How I built it

  • Backend: Python with a standard-library HTTP server, SQLite for storage, and cryptography (Fernet) to encrypt stored OAuth tokens and IMAP passwords.
  • Frontend: React 19, TypeScript, Vite and Tailwind CSS v4, with Three.js for the landing-page art and zxing-wasm for camera scanning.
  • AI: OpenAI's Responses API with gpt-5.4-mini, used in three places: benefit extraction, the weekly digest and the assistant. Extraction and the digest use strict structured outputs, so the model must reply in a fixed JSON schema, including a confidence level (explicit, computed, ambiguous, unknown) for every expiry date.
  • Integrations: Gmail API and Google OAuth (PKCE), Microsoft Graph for Outlook, IMAP over TLS, and SMTP for reminder emails. All calls use Python's urllib, with no vendor SDKs.
  • Demo: a server-free version of the whole interface with sample data, deployed on Vercel, plus a promo video made with Remotion.
  • Tooling: 115 pytest tests, and Claude Code for development help.

The key design rule is that the AI only reads; plain code decides. Dates, reminders, card reset schedules and loyalty detection are all ordinary code. The model fills in benefit records and nothing else: it can't send emails, trigger actions or mark its own output as reviewed.

Challenges I ran into

  • Wrong dates are worse than missing ones. A reminder on the wrong day gives false confidence. The prompt's central rule is never guess a date, and code backs it up: a date marked ambiguous or unknown is removed and the benefit goes to the review queue with a reason.
  • Real emails are messy. Our first real Gmail scan got 15 of 22 benefits fully right: every value and voucher code matched, but 3 dates were missed, 1 was a duplicate and 3 weren't benefits at all (credit-card ads, newsletters). We fixed Singapore day/month dates, "end of October", date ranges and duplicate handling, and a second 50-email scan got 11 of 13 right, with the other 2 caught by review.
  • Hallucinated details. A made-up voucher code is worse than none at the till, so every code must appear word for word in the source email or it's dropped. The digest drops any benefit ID the model invents.
  • Credit-card reset logic. Monthly, quarterly, half-yearly, calendar-year and anniversary credits all reset differently, including leap years and partial use ("$7 of $15 spent this month").
  • Cost and abuse. We capped AI reads at 100 emails per user per day, filtered marketing without AI, rate-limited questions, digests and scans, and cached the digest until something changes.

Accomplishments that I'm proud of

  • A full working app, not a mock-up: three inbox providers, 25 credit cards, reminders, review queue, digest and assistant.
  • AI guardrails that are enforced in code, not just requested in a prompt.
  • Privacy by design: read-only inbox access, encrypted tokens, store: false on every OpenAI request, and full account deletion.
  • 115 automated tests that block any real network call, including checks that one user can never see or change another's benefits.
  • A live demo anyone can try in the browser without installing anything.

What I learned

  • Structured outputs plus a confidence field turn an unreliable free-text answer into something code can check.
  • Testing on real emails finds problems that made-up examples never do.
  • A small, cheap model (gpt-5.4-mini, about 7x cheaper than our fallback) is enough when the prompt is precise and code handles the rest.
  • Letting the user confirm uncertain items builds more trust than trying to be right every time.

What's next for Squirrel

  • More credit cards and loyalty programs, with a way to keep their rules up to date.
  • Production hosting: Google and Microsoft app verification, HTTPS, a proper email service and a production database, so it can open beyond a small group of testers.
  • Push notifications and a mobile app.

Built With

Share this project:

Updates

Submission history