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.
Expiry Tracker
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
# 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
- Items are stored in
~/.expiry_tracker.json— a simple JSON database - Each item has: name, category, purchase date, expiry date, quantity, optional note
- Default shelf life is inferred from category (dairy=7d, meat=3d, bread=5d, etc.)
todaycommand shows items expiring within 48h, sorted by urgencyreportshows 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
-
Forgetting to remove consumed items. Always run
removewhen you eat something, otherwise the waste report is inaccurate. -
Overly optimistic expiry dates. "Best before" ≠ "goes bad on." Use smell/visual check before tossing. The tracker errs on the side of caution.
-
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.
-
Ignoring the
todaycommand. Set up a daily cron/reminder to check it every morning.
Verification Checklist
- Database file created at
~/.expiry_tracker.json -
addcommand works with both--daysand--expiryflags -
list --days 3shows only items expiring within 3 days -
todayshows actionable suggestions -
reportshows waste statistics -
batchmode parses comma-separated items correctly
- Downloads
- Security audit
- Pass
- Last updated
- 3mo ago
- Current version
- v0.1.1
- License
- MIT-0
