lawandrorder/mate

What this is

Mate is a text-first shopping agent: you message it before you shop and it handles cashback, personal discount codes, package tracking and price-drop alerts. The live product at mate.fm connects these requests to a merchant network.

This repository is the open-source starter, not the production service: it contains a small runnable agent, a web chat demo, docs, a set of original icons, and clearly labeled demo providers. It is not connected to the live merchant network, and every reply in the starter is marked [demo].

It fits people who want to see how a shopping assistant is structured, run the demo locally, or reuse the icon set and provider interfaces. It does not give real cashback, codes or shipping data.

Quickstart

The starter requires Python 3.10 or newer and no third-party runtime packages. Clone the repo, enter the directory, then run the CLI or the web chat:

git clone https://github.com/lawandrorder/mate.git
cd mate
python -m mate chat "cashback at Demo Shop"
python -m mate serve

Then open the local server at http://127.0.0.1:8080. Other sample inputs cover codes, tracking and price watches, for example python -m mate "code for Demo Shop", python -m mate "track DEMO-123456", and python -m mate watch --simulate-drop. Run the test suite with python -m unittest discover -s tests -v.

A Docker path is also available:

docker build -t mate-starter .
docker run --rm -p 8080:8080 mate-starter

All settings are optional for the local demo. If you want the optional OpenRouter fallback for unrecognized messages, copy .env.example and set OPENROUTER_API_KEY; MATE_HOST, MATE_PORT and MATE_DATA_DIR control the server address, port and JSON storage directory.

How the demo works

The agent parses an incoming message into an intent — cashback, code, tracking, price watch — and routes it to the corresponding provider. In this repository those providers are demo implementations: placeholder links, DEMO-… codes, scripted shipment statuses, and a local price watch that does not scrape live product pages. The optional LLM fallback only runs when intent parsing fails, and no API keys are hardcoded.

The web chat is a demo interface; the Twilio adapter under POST /webhooks/twilio is a stub that reads Body and From and replies with TwiML without sending real SMS. Signature validation is off by default (TWILIO_VALIDATE_SIGNATURE=0) and can be required by setting it to 1.

Constraints

• The starter is a demo and does not provide real cashback, discount codes, deliveries or cashback offers. Demo replies are labeled [demo].
• Production delivery and the merchant network remain on mate.fm; this repository keeps SMS and web paths and does not implement live provider adapters.
• Python 3.10+ is required; the Docker image is an alternative for local serving.
• The Twilio adapter does not send SMS and is only a webhook stub unless you wire it to your own service.
• The license is MIT.

HotRepo's take

The repository appeared on HotRepo's new-project list on 2026-11-12, gaining 116 stars and 3 forks in roughly 1 hour 40 minutes from its first observed snapshot. There is no daily all-language rank recorded and no discussion data. The README is explicit that this is a starter, not the live Mate service: the useful parts are the intent-routing skeleton, the runnable local demo, the docs and an original icon set. Readers looking for working cashback or tracking should treat the repo as a scaffold and go to the live product instead.