CLIP(7)

Project Documentation

NAME

clip — self-hosted, shared household shopping lists

DESCRIPTION

Clip is a self-hosted shopping-list application designed for a household using several devices. Members can create lists, add items, and check off purchases while changes are synchronized between connected browsers. A phone-first interface supports everyday shopping, while an HTTP API enables item and recipe imports from automation tools.

Project status: Active development and household testing. The capabilities below are implemented; AI sorting and store-specific information are described separately as planned work.

FEATURES

Multiple shared lists. Create separate lists for weekly groceries, errands, or other household needs. Switch lists by selecting the current list name.
Live synchronization. WebSocket updates keep connected members informed of changes. Incoming updates preserve unfinished item text, input focus, and selection.
Quantity-aware entry. Enter an item with its quantity and unit, such as 2 l mjölk. Clip displays the capitalized item name with its quantity: Mjölk · 2 l.
Shopping progress. Check and uncheck items, distinguish outstanding items from checked items, and clear completed purchases.
Passkeys and household invitations. Sign in with a registered passkey, use recovery codes when needed, and invite additional members with a shareable link.
Personal appearance. Choose from seven themes with live previews. Saved preferences follow the user across devices.
Automation support. Import groups of items through an authenticated API. Recipe imports are atomic: all items and their events are saved together, or none are.
Home Screen access. Add Clip from the browser to the phone’s Home Screen for a standalone application view.

USAGE

Join and sign in. Open the Clip installation provided by your household administrator. Follow an invitation or use an available recovery code, then register a passkey in Settings.
Select or create a list. Tap the current list name to open the quick switcher. Choose an existing list or select + New list. Cancelling the creation dialog preserves your unfinished item entry.
Add items. Type an item name, optionally including a quantity and unit. Add the item to make it available to the household.
Shop together. Check items as they are collected. Other connected members see the updated state without needing to reload the page.
Manage lists and preferences. Use the top-right menu to open Lists or Settings. Settings contains appearance, credential management, and Sign out.

The connection indicator reports Live, Reconnecting, or Offline. After a connection interruption, Clip catches up on missed changes. It does not currently provide offline editing: offline navigation shows a reconnect page rather than a cached private list.

PERMISSIONS

Members can create household lists and delete lists they created. Household owners can delete any household list. Deleting a list removes its items as well. Owners manage invitations and agent tokens, including revocation and permanent deletion.

A user can register multiple passkeys. Registration checks against active Clip credentials to prevent reusing an authenticator that already holds an active Clip passkey. This relies on credential recognition, not a physical hardware serial number; a reset key cannot be identified through erased credentials.

Agent tokens provide revocable API access for automation. Authenticated pages and API responses are excluded from offline caching; the service worker caches public assets such as stylesheets, scripts, and icons.

ARCHITECTURE

Clip runs as one Rust service with SQLite storage. It serves a browser interface and an HTTP API, while authenticated WebSocket connections distribute household changes. An event log supports replay after reconnecting.

Nginx can terminate HTTPS in front of the service, including in a Docker Compose deployment. Browser-facing HTTPS, the application origin, and the passkey relying-party configuration must agree. Application data persists separately from the container image.

Automation clients can import items in batches rather than submitting one request per item. Reusing HTTP connections and batching requests reduce overhead. Ongoing performance work targets event-history lookup costs and redundant list refreshes.

ROADMAP

The following capabilities are under development or proposed. They are not part of the completed shopping workflow described above.

Owner-managed AI connection. Configure a model provider, server URL, model, and optional API key in Settings, with connection testing. Ollama is the initial target, with support planned for OpenAI-compatible services.
AI sort. An explicit button will organize items into categories such as fruit and vegetables, dairy, meat, and frozen food. Sorting must preserve items, quantities, and checked states, and will work without selecting a store.
Store selection. Optionally associate a new list with a specific branch, distinguishing locations belonging to the same retail chain.
Store-specific item locations. Store integrations will retrieve available shelf or section information for the selected branch. Locations must come from actual store data, with the model assisting item matching rather than inventing shelf numbers.

Without a selected store, Clip will not display shelf information, location placeholders, or store-lookup indicators, and will not run store-location lookups. User-requested AI category grouping is independent of these store-specific features.

Normal list operations must remain available when a model service or store integration is unavailable.