HomeStoq is a pantry management system that runs on your home network. It tracks what you have, what you need, and updates automatically through receipt scanning and voice commands.
The problem it solves: Manually tracking groceries is tedious and you forget what's in the pantry. HomeStoq automates this by extracting items from receipt photos and listening to your existing voice assistant.
# 1. Setup
npm run setup
# Edit .env and add your GEMINI_API_KEY
# Optional: Add GOOGLE_USERNAME/PASSWORD for auto-login (NOT recommended with 2FA)First time? Open
http://localhost:6080to log into Google Keep via noVNC (auto-redirects to vnc_auto.html). If you have 2FA enabled, do NOT add Google credentials to.env— use manual login instead to avoid approval spam.
┌─────────────────────────────────────────────────────────────┐
│ Input Methods │
├─────────────────┬─────────────────┬─────────────────────────┤
│ Phone camera │ Web browser │ Voice command │
│ (receipt) │ (manual/chat) │ (Google Keep) │
└────────┬────────┴────────┬────────┴────────────┬────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────┐ ┌──────────────────────────┐
│ HomeStoq App (Docker) │◄─────┤ Keep Scraper (Docker) │
│ - AI Vision (Gemini) │ │ - Xvfb Virtual Display │
│ - Chat & Shopping │ │ - Anti-detection Headed │
│ (Gemini/OpenRouter) │ │ │
└────────────┬─────────────┘ └─────────────┬────────────┘
│ │
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────┐
│ SQLite Database │ │ Chrome Profile │
│ (Persistent Vol) │ │ (Persistent Vol) │
└──────────────────────────┘ └──────────────────────────┘
Hybrid AI Architecture:
- Vision (Receipt OCR): Always uses Google Gemini for reliable multimodal support
- Chat/Voice/Shopping: Configurable provider — Gemini (default) or OpenRouter for cost optimization
- Automatic Fallback: Vision uses model fallback chain; general operations can cross-provider fallback
Anti-Detection Engine: The scraper runs a real, "Headed" Chrome instance inside a virtual desktop (Xvfb). This makes the automation indistinguishable from a human user. It supports Automatic Login via environment variables and provides a noVNC web interface (port 6080) for manual 2FA verification.
| Situation | Action | Result |
|---|---|---|
| After shopping | Scan receipt photo | Items added to inventory |
| Running low | "Hey Google, we're out of coffee" | Stock decreases |
| Before shopping | Chat: "What should I buy?" | AI suggests based on habits |
| Checking stock | Ask: "How much rice is left?" | Instant quantity |
📖 Usage Guide for detailed workflows
| Guide | Contents |
|---|---|
| 01 - Getting Started | Installation, setup, troubleshooting |
| 02 - Usage Guide | Daily workflows, voice commands |
| 03 - Configuration | All config.ini options |
| 04 - Architecture | System design |
| 05 - API Reference | Endpoints |
| 06 - Database | Schema |
| 07 - Scraper Deep-Dive | CDP mode, anti-detection |
| 08 - Development | Building and contributing |
- Backend: ASP.NET Core 10 (Minimal APIs)
- Frontend: Vanilla HTML/CSS/JS + Alpine.js
- Database: SQLite + Entity Framework
- AI: Google Gemini (vision + configurable provider for chat)
- Browser Automation: Chrome DevTools Protocol
- Deployment: Docker or bare metal
Planned features in GitHub Issues:
- Push notifications for voice command processing
- Analytics dashboard (historical trends)
- Mobile-optimized receipt scanning UI
- Scraper health monitoring
MIT License — see LICENSE.md
Built in Sweden by Christian Gennari