A shopping list that remembers what you buy.
Works offline on Android. Add an optional server to share lists and edit them in your browser.
Download Android APK · Get started · Phone + browser · Documentation
Apache-2.0 · Offline first · No telemetry
The same shopping list: Grove with Artwork, or Tide with Plain.
Grove light · Tide dark
Usuals remembers the shops you finish, so your next list starts with a little more context. The Android app works on its own without an account, a server or a model. The familiar colour collage stays with your list while names, quantities and checkboxes remain easy to read.
Choose Plum, Grove or Tide in Settings > Appearance on Android or Preferences > Appearance in the browser. Each follows your device's light or dark appearance; Android's choice also carries through to the widget. Choose Artwork for the layered-paper background or Plain for quiet surfaces, independently of the palette. Both choices stay on this device. Preview the three palettes.
These everyday shopping tools are available on Android:
| When you want to… | Usuals helps you… |
|---|---|
| Catch what you need | Type, dictate, share text or scan a barcode. Edit names, quantities, notes, categories and store tags. Open the list quickly from its home-screen widget. |
| Remember the last shop | Finish a shop to save checked items as dated purchases. Keep unchecked rows open, undo a finish, search history and rebuy selected items. |
| Keep essentials coming | Set explicit repeat rules, pin favourites and review past purchases in short rounds. Quantity hints wait for a tap; similar names merge only with your approval. |
| Bring a recipe along | Share a recipe link, review its ingredients and choose what to add. Existing list items are excluded; pantry staples and recent purchases start unticked. |
| Move through the shop | Use shopping mode, store filters and aisle order. Defer an item to the next finished shop, or opt into a weekly local reminder. After finishing in shopping mode, open your chosen Wallet app. |
| Pack for an occasion | Create a personal pack or save the current list, edit its items, then review selections and quantities each time you use it. Existing list items stay unchanged. |
| Keep receipts | Attach a receipt photo to a finished shop, or read one with your optional image model, compare corrections with the original photo and zoom, and save reviewed items and dates into History. |
| Keep your history | Import a dated past list, share a list as text, or export and import shopping data through Android's file picker. |
Suggestions wait for your approval. Only repeat rules you set add items automatically; purchase memory, favourites and review work without AI.
Purchase memory, favourites and review
Favourites in the list's More options menu are personal shortcuts. Save an item from its editor, then tap it in Favourites when you need it again. Items already on the list are marked; favourites never add themselves automatically.
As you type, matching names come from the current list's purchase history. Don't suggest again hides an item from typing suggestions and history review on this phone. You can still add it yourself. If it has a repeat rule, Usuals asks before stopping that rule too.
Tap the Replay arrow beside History above the Android list for Review your usuals: past purchases one at a time, up to ten per round. Add saves immediately; Skip affects only this review. Undo last choice restores a skipped card or removes an unchanged item added by this review. Close whenever you like, or choose Review more at the end. Ranking uses the last eight shops: frequency, recent-shop coverage for ties, then time since purchase. Current items, purchases from the last 24 hours, muted or snoozed items and repeat-rule items are excluded. Inferred interval predictions remain disabled until replay over real household history beats both comparison baselines. The six-step first-run tour introduces this shortcut. Reopen it from Settings > Help and about > Guided tour.
In History, open the collapsed Shopping stats section for saved-shop, recorded-item and different-item totals, plus your five most frequent recent usuals. Counts belong to the selected list and include imported shops. The same section is available in browser History. How stats are counted.
Remove a saved shop from History > Shop options > Delete shop on Android, or Delete shop inside a shop in browser History. Confirm the date before deleting. This removes the whole shop, all its purchases and any local receipt photo, without changing the current list. On shared lists it removes the shop for everyone. Deletion cannot be undone. Account lists need a server that supports history deletion; Android remembers verified support for offline use.
To move an item, open its editor and choose More actions > Move or copy to another list. Choose an active list and whether to keep the original. The new row is unchecked and keeps its details. Moves between account lists confirm the destination first; if the connection or either list changes, the original stays available.
Personal occasion packs
Open More options > Favourites > Occasion packs on Android, or List options > Occasion packs in the browser. Create a pack from scratch or save the current list, where checked rows start unselected. Edit its name, items and details without changing the shopping list.
Review and add opens a separate review each time. Choose items and adjust quantities for this use without changing the saved template. Checked and unchecked items already on the list, including aliases and rows hidden by a store filter, cannot be added again. An item added by someone else while you review keeps its quantity and details.
Packs stay on this device for the current account; they do not sync between phone and browser. Android includes them in shopping-data exports; pack files can also be exchanged with the browser. Only the items you confirm enter the list and follow its usual synchronization. Local Android lists need no server. For account lists, Android verifies server support before queuing pack additions and can use previously verified support offline. See the occasion pack guide for ownership, transfer and older-server behavior.
Receipts and Wallet
In History, open Import receipt photo from the menu to read a receipt or enter its items yourself. When using server AI, update your Usuals server along with the app to enable receipt reading. Review the date, item names and quantities before saving the purchases and photo. Compare a correction with the original photo and open its zoom viewer while reviewing. Use Add receipt on an existing shop to keep a photo without model calls or duplicate purchases. Tap a photo to enlarge and zoom. Photos stay on this phone, travel in shopping-data exports and direct device transfers, and can be saved as individual JPEGs. They are not synced or shared with a list.
Shopping mode keeps Finish shop reachable at the bottom. It records the displayed checked items as purchases, preserving rows outside the store filter and concurrent changes; Undo remains available. Normal list mode keeps its inline Finish action.
After Finish shop in shopping mode, Open Wallet opens the app you chose. The first tap uses Android’s app picker. Change it under Favourites > Shopping preferences > Choose wallet app. Usuals launches the app without reading its contents or initiating a payment. Undo remains available after returning.
Finish the shop, then find its purchases in History. These are saved synthetic groceries in the running Android app.
On Android, the scanner pauses after each accepted barcode. Choose Scan next item when you are ready; keeping one package in view does not fill the list with copies.
Optional Open Food Facts lookup suggests a name and category, with brand and pack size when available. Confirm the name once and reuse it offline. Missing records can be named manually.
Product details shows ingredients, Nutri-Score, NOVA, declared allergens and traces. Saved details remain available offline with a saved date, explicit refresh and source link. Community data can be incomplete or outdated; check the packaging for ingredients and allergens. Product data is credited to Open Food Facts under the ODbL.
On Android, share a note or recipe URL, or choose More options > Import recipe or list. Plain text and Markdown are read locally. Structured recipes are read directly on the phone without a model. Review the proposed items before adding; recipe imports avoid existing list items and preserve your review choices.
The browser's List options > Import list or recipe also offers text, file and photo imports with review. An optional model using OpenAI-compatible Chat Completions, including Ollama and Anthropic-compatible endpoints, can read prose recipes or, with image support, photos of written lists. AI is off by default. Selecting a photo does not send it: you must request a read, its image check must succeed, and you review the result before adding items.
Signed in, Settings > Account > AI assistance uses the server's configured provider. Provider and model details remain available before use. See provider setup for the server gateway and advanced direct options. The everyday list needs no AI service.
Android text and Markdown import formats
Plain lists use one item per line. Bullets, numbered lists and checkboxes are
supported. Ticked entries arrive ticked, so a reused list comes in as it was.
Enable Repeated emoji set the quantity to read Cerveza 🍺🍺🍺 as 3 Cerveza;
otherwise emoji stay in the name. A Markdown heading such as # Weekend shopping
sets a custom note title. Long notes are added in the background, batch by batch,
so the list stays usable.
Use Android alone, or sign in to a Usuals server that you or someone you trust runs. Signed in, your lists live in your account on that server. The phone and browser show the same lists; the phone keeps an offline copy and sends pending changes when it is back online.
In the web app, Account > Connect a phone offers a QR code. Without a computer, you can sign in using the phone's browser. The connection guide explains both flows.
Choose Share on a list to add other accounts on the same server. Everyone added can edit the list and add others; the owner can remove people or delete the list, and anyone else can leave it. Some server configurations also offer email invitations. Account and invitation options depend on the server you choose.
Shared-list notifications start off. On Android, open Settings > Notifications to choose silent alerts for items added and shops finished by other people. Each type can be switched off, or disable shared alerts together. Delivery follows background sync, usually around 15 minutes and sometimes delayed by Android. There are no alerts while Usuals is open. The browser offers optional quiet in-app notices for other lists under Preferences > Notifications. These choices stay on the device and account. See the notification design.
The current browser interface, populated with a synthetic account-list fixture.
| Part | What it does |
|---|---|
| Android | Offline lists, purchase history, capture and shopping tools. Signing in is optional and connects your lists to an account. |
| Web | Account lists, capture and import, sharing, phone pairing and account management. Sign-in options depend on the server configuration. |
| Server | A Kotlin/Ktor service with PostgreSQL that stores account lists, applies changes and serves the web app. You run it on your infrastructure. |
The server and its operator can read account lists. Encryption at rest protects a copied database or backup, not a running server. Lists on a phone that is not signed in never leave it. Read the privacy policy, browser boundary and account guide before choosing a server.
Running a server also means operating its database, access controls, backups and recovery. The deployment package provides preparation material and operational checks; it does not provide a hosted instance.
Usuals Cloud is a separate managed-hosting project. This release does not offer a hosted subscription. Offline Android and self-hosted use remain free. The hosting plan records the service boundary and launch requirements.
- No telemetry, analytics, advertising, crash reporting or Play Services. Lists, local purchase history and suggestions work without a network.
- Direct, optional reads. Native recipe URL requests go from the phone to the recipe site. Enabled barcode lookup sends the code to Open Food Facts, not your list or purchase history. No application server proxies either read.
- Explicit AI requests. The configured model receives submitted recipe text or photos after an explicit action. Server AI sends those inputs through your chosen server and stores personal provider keys encrypted there. Direct native provider keys stay in Android Keystore.
- Speech follows Android's service. Availability and audio processing depend on the selected speech service; keyboard capture works offline.
- Portable shopping data. Export/import and Android device transfer preserve shopping history. Cloud backup and secret transfer are excluded. Account credentials, sync state and the product cache are outside shopping exports.
See the security model for the complete trust boundaries.
Download the signed Android APK from GitHub Releases, or add
https://github.com/vitofico/usuals to Obtainium
for updates. The one-tap Obtainium import selects only
stable production APKs.
GitHub CI builds, signs and publishes updates after the Android and server checks pass. Usuals is not available on F-Droid. See the distribution guide for signatures, checksums and inclusion status; the corrected F-Droid draft remains unsubmitted.
Android works offline without an account. Sync and shared lists use a compatible server of your choice. Read the privacy policy before enabling external services.
The first launch includes a guided tour. Skip it whenever you like and reopen it from Settings > Help and about > Guided tour on Android or Preferences > Guided tour in the browser.
To build Android, install Git and Docker, then run:
git clone https://github.com/vitofico/usuals.git
cd usuals
scripts/dgradle :app:assembleDebug test --no-watch-fsThe APK is app/build/outputs/apk/debug/app-debug.apk. With Android platform-tools
installed, select your emulator explicitly:
adb -s emulator-5554 install -r app/build/outputs/apk/debug/app-debug.apkEvery Gradle build and test uses scripts/dgradle. For the server's real
PostgreSQL integration suite and distribution build:
server/scripts/test-localUse the server guide and deployment runbook for instance preparation. Production deployment is an explicit operator action. The development guide covers full tests, native 16 KB alignment, emulator checks and suggestion replay. See the verification record and known issues for tested scope and remaining limits.
English is the default. Spanish, Italian, French and German are included in both the Android interface and the web editor. Input languages are independent of the display language.
Android translations are complete values-xx/ resource folders, with automatic
locale discovery and parity checks. The browser uses complete locale catalogs.
No registry change is needed to add a language. The
translation guide explains the workflow, helper script and
glossary; you can improve the copy without installing Android tooling.
Read the contribution guide, architecture and roadmap. Preserve migration paths, optional network access and fast offline capture.
Maintained by @vitofico.
Apache License 2.0. Bundled dependencies and fonts retain their own licenses and notices. See the contribution agreement.
If Usuals is useful to you and you'd like to chip in, you can buy me a coffee:
