Everyday Runtime

An open-source, self-hosted shopping assistant that learns what a household probably needs — without requiring perfect inventory tracking.

Website: https://micha16372.github.io/everyday-runtime/ · Try it in three minutes: DEMO.md

🇩🇪 Auf Deutsch: Everyday Runtime ist ein selbst gehosteter Einkaufsassistent, der erkennt, was ein Haushalt wahrscheinlich braucht — mit Wahrscheinlichkeit und Begründung, ohne exakte Vorratshaltung. Wohin es geht (Familien, WGs, Fürsorge für Eltern, Preis-Radar, Alexa, Hausgeräte, Fotos): Vision auf Deutsch.

Milk — probably low · 89% Last purchased 6 days ago · usual interval ~5 days

Everyday Runtime is built as a Twenty app. It runs on your own Twenty server, keeps your data there, and needs no AI service, no cloud account and no API key to work.

The problem

Shopping lists fail in two ways:

• Plain lists only know what someone remembered to write down. Everyone else in the household finds out that the milk is gone when the fridge is open.
• Inventory apps promise to know what is in the house — if you scan every item in and every item out. Nobody does that for long, and a stock count that is wrong is worse than none.

Real households have partial information: a receipt here, “we're out of coffee” there, a glance into the pantry. Everyday Runtime is designed for exactly that.

How it is different

	Plain shopping list	Inventory tracker	Everyday Runtime
What you record	Items to buy	Every item in and out	Whatever you happen to know
What it knows	Only what's written	An exact count (in theory)	A probability with a reason
When data is missing	Silent	Wrong	Says it is unsure
Suggests items	No	Rarely	Yes, and explains why

The core idea is a small, explicit pipeline:

Product → Observation → Estimated state → Confidence → Need → Shopping action → Purchase / outcome

It never pretends to know a stock level. It says “Milk is probably low — 89%”, shows the evidence, and lets you correct it with one tap (“Still have it”, “Empty”). Direct reports are shown as Confirmed; everything inferred is visibly an Estimate.

Features (v0.1)

• Now — a calm overview of what is probably needed, with percentage, a plain headline (“Probably low”, “Possibly getting low”) and a one-line reason.
• Why? on every suggestion — the full explanation: number of purchases, regularity, expected run-out, conflicting reports, stale data.
• Shopping list — quick add (2 milk, coffee x3), items added by you vs. suggested items (with the confidence at the time), mark as bought with quantity, optional price and store, “Not now” for suggestions.
• Products — search, create, and per-product details: last bought, usual interval, confidence, recent evidence; actions It’s empty, Still have it, Bought, Add to list, Archive.
• Activity — every observation, grouped by day. This is exactly the evidence the engine uses.
• Talk to your list — “Milch ist leer”, “2 Kaffee auf die Liste”, “Was brauchen wir?”: understood for free and offline in German and English; optional AI tools for Twenty's AI chat (docs/AI.md).
• Home Assistant — the list as a to-do list (checking off counts as a purchase), “probably needed” sensors, Assist voice sentences in German and English; installable via HACS (docs/HOME_ASSISTANT.md).
• Alexa — your own private skill: “Alexa, sage mein Vorrat, Milch ist leer”, plus a bridge that moves Alexa's own shopping list into Everyday (docs/ALEXA.md).
• Integrations — MCP for any AI assistant, POST /s/talk for Siri shortcuts, n8n and bots, Twenty workflow actions (docs/INTEGRATIONS.md).
• Active questions — “Still enough coffee?”: one tap where it helps most.
• Price radar — usual price, recent low, “great / good / usual / expensive” while you type a price, price alerts and a stock-up recommendation with the estimated saving; community prices from Open Food Facts by barcode, on request.
• Deutsch und Englisch — the whole app, including every explanation.
• Demo household — five products (Milk, Coffee, Paper towels, Pasta, Apples) that show every rule of the engine within a minute.
• GET /s/needs — an authenticated JSON endpoint with the same results, for dashboards and future integrations.
• Mobile-friendly layout, light and dark mode, real buttons with labels and large tap targets (see the known accessibility limitation in CHANGELOG.md).

Screenshots

Now (phone)	Shopping list (phone)	Product details (dark)

How it works

src/
  domain/        Pure TypeScript: inference engine, list logic, texts, demo data (no Twenty, no React)
  data/          Twenty REST repository + named user actions (the only code that writes)
  ui/            React screens rendered by one Twenty front component
  objects/       Product, Observation, ShoppingItem, Purchase
  logic-functions/  GET /s/needs and the health check

The inference engine (src/domain/inference.ts) is deterministic and has no hidden state: the same observations at the same moment always give the same result. In short:

Evidence	Effect
Marked empty / added as needed	Confirmed, very high need (95% / 90%)
Bought in the last 2 days	Confirmed in stock, need ≤ 5%
Seen in stock in the last day	Confirmed in stock, need ≤ 10%
Regular purchases	Need rises around the usual interval (median of recent intervals)
Purchase quantities	3 l last longer than 1 l — based on your typical use per day
Earlier “Empty” / “Still have it” reports	The expected duration is adjusted (bounded, explained)
Irregular purchases / only one purchase	Same idea, lower confidence → “possible”
“Used some” since the last purchase	Expected run-out moves earlier
“Empty” then “still have it” within a day	Conflict → “Unclear — please check”
Old evidence	Confidence and need drift back towards “don’t know”
No data	Unknown — never suggested

Details, formulas and the reasoning behind them: docs/ARCHITECTURE.md and docs/PRODUCT_PRINCIPLES.md.

Quick start

Requirements: Node.js 24 (see .nvmrc), Yarn 4 (via Corepack), Docker.

git clone https://github.com/micha16372/everyday-runtime.git
cd everyday-runtime
corepack enable
yarn install
yarn twenty docker:start   # local Twenty server on http://localhost:2020
yarn twenty apply          # build, register and install the app

Open http://localhost:2020, sign in with the development account tim@apple.dev / tim@apple.dev, choose Everyday Runtime in the sidebar and press Load demo household.

New here? DEMO.md walks through the whole workflow in three minutes.

The first start of the Twenty container takes a few minutes. If yarn twenty apply fails with ECONNRESET right after docker:start, the server is still warming up — wait a minute and run it again. More in SETUP.md.

Local development

yarn twenty dev          # watch mode: rebuilds and syncs on every change
yarn lint                # oxlint
yarn typecheck           # TypeScript (tsgo)
yarn test                # unit tests: engine, list logic, repository, actions
yarn test:integration    # end-to-end workflow against a running Twenty server

yarn test:integration installs the app into the server it runs against and uninstalls it afterwards; run yarn twenty apply again if you want to keep using the app locally.

Self-hosting and privacy

• All data lives in your Twenty workspace database. Everyday Runtime has no backend of its own and no telemetry.
• No AI provider. The engine is plain arithmetic you can read and test.
• The only outside call is optional and on request: “Community prices” sends a product's barcode (nothing else) to Open Food Facts / Open Prices.
• Access follows Twenty's permissions: the UI and the /s/needs route act as the signed-in person.

See docs/PRIVACY.md for what is stored and how to delete it.

Roadmap

• v0.3 — German UI, active questions, price radar ✅
• v0.4 — talk to your list (free sentence understanding, AI tools for Twenty's AI chat) ✅
• v0.5 — households with several people, care mode for relatives, shared-flat mode
• v0.6 — capture by barcode, photo, receipt
• v0.7 — webhooks, appliance adapters, one-tap ordering (confirmed); Home Assistant and Alexa arrived early ✅
• v1.0 — stable self-hosted workflow, upgrade docs, documented privacy model

Full list: ROADMAP.md · where it is heading: VISION.md (Deutsch).

Contributing

Contributions are welcome — especially real-world feedback on suggestions that felt wrong. Start with CONTRIBUTING.md and the issues labelled good first issue.

• Questions and ideas: Discussions · help: SUPPORT.md
• Security issues: SECURITY.md (private reporting only)
• Community rules: CODE_OF_CONDUCT.md · maintainers: MAINTAINERS.md
• Releases: GitHub releases · notable changes: CHANGELOG.md

License

MIT