expiry-tracker

Track food expiry dates from grocery receipts. Get daily alerts before food goes bad, 'use this today' suggestions, and reduce food waste. Scan receipts or add items manually.

Overview

Food waste is a massive problem — the average household throws away 30% of the food they buy. Most of it spoils simply because people forget what's in the fridge and when it expires.

Expiry Tracker solves this by maintaining a simple inventory of perishable items with their expiry dates, then proactively suggesting what to cook before things go bad.

When to Use

• After grocery shopping — add items to track
• Daily check — "what expires soon?"
• Before cooking — "what should I use today?"
• When planning meals for the week
• Before traveling — check what needs to be consumed first

Don't use for: Non-perishables (pasta, rice, canned goods with 1+ year shelf life), frozen items (unless thawing).

Commands

bash

# Add an item
python scripts/expiry_tracker.py add "milk" --days 7
python scripts/expiry_tracker.py add "chicken breast" --expiry 2026-08-15

# List items expiring soon
python scripts/expiry_tracker.py list --days 3

# Get today's "use this first" suggestions
python scripts/expiry_tracker.py today

# Remove consumed/expired item
python scripts/expiry_tracker.py remove "milk"

# Show full inventory sorted by expiry
python scripts/expiry_tracker.py inventory

# Weekly summary / waste report
python scripts/expiry_tracker.py report

# Bulk add from receipt text
python scripts/expiry_tracker.py batch "milk, eggs, bread, chicken, yogurt"

How It Works

1. Items are stored in ~/.expiry_tracker.json — a simple JSON database
2. Each item has: name, category, purchase date, expiry date, quantity, optional note
3. Default shelf life is inferred from category (dairy=7d, meat=3d, bread=5d, etc.)
4. today command shows items expiring within 48h, sorted by urgency
5. report shows waste statistics: how much expired vs consumed

Default Shelf Life by Category

Category	Days	Examples
Dairy	7	Milk, yogurt, cheese
Meat	3	Chicken, beef, pork, fish
Produce-Leafy	4	Spinach, lettuce, herbs
Produce-Root	14	Carrots, potatoes, onions
Produce-Fruit	7	Berries, bananas, apples
Bakery	5	Bread, pastries, tortillas
Deli	5	Cold cuts, prepared salads
Eggs	21	Eggs
Condiments	180	Opened sauces, dressings
Tofu	7	Tofu, tempeh

Common Pitfalls

1. Forgetting to remove consumed items. Always run remove when you eat something, otherwise the waste report is inaccurate.

2. Overly optimistic expiry dates. "Best before" ≠ "goes bad on." Use smell/visual check before tossing. The tracker errs on the side of caution.

3. Not adding items on shopping day. The tracker is only as good as its data. Make it a habit to batch-add after unpacking groceries.

4. Ignoring the today command. Set up a daily cron/reminder to check it every morning.

Verification Checklist

• Database file created at ~/.expiry_tracker.json
• add command works with both --days and --expiry flags
• list --days 3 shows only items expiring within 3 days
• today shows actionable suggestions
• report shows waste statistics
• batch mode parses comma-separated items correctly