cheapo

cheapo

A CLI that finds all those free games from all those game stores. And, if you want, posts them to a Chatto channel.

Free games CLI in Go — lists current free game offers (Epic Games Store, Steam) and can use watch to wait for new free games.

Inspired by / reference: free-games-claimer (a fork of vogler/free-games-claimer) and free-games-notifier. Unlike the reference projects, we need no browser and no login: we read the public store endpoints directly (details: AGENTS.md). Claiming the games is not part of this tool — it only detects and reports them.

Install / build

go build -o bin/cheapo ./cmd/cheapo

Prerequisites: Go ≥ 1.27. For linting: gopls (go install golang.org/x/tools/gopls@latest), formatting with gofmt (details: AGENTS.md).

Usage

# Games free right now (Germany, German)
cheapo list

# As JSON (e.g. for further processing / bot)
cheapo list --json

# Other region / locale
cheapo list --country AT --locale en-US

# Wait for new free games (polling every 15 min, baseline = current state)
cheapo watch

# Different interval, single check
cheapo watch --interval 5m
cheapo watch --once

# Other stores / upcoming free games (preview, Epic only)
cheapo list --store steam
cheapo list --store gog
cheapo list --store all
cheapo list --upcoming

Example output:

🎮 [epic] Monument Valley
   By: Netflix, Inc.
   Instead of: 6.99 €
   Free until: 02.11.2026 17:00 (CET)
   https://store.epicgames.com/en-US/p/monument-valley-1d99d3

cheapo watch is suitable as a long runner for a systemd service or cron/timer; every newly detected game is reported on stderr as soon as a poll finds it.

MCP server

cheapo mcp exposes the free games data as an MCP server. Two transports:

# HTTP (Streamable HTTP) — the mode for remote clients, agents, monitoring
cheapo mcp --http 127.0.0.1:8080

# stdio — only for clients that start the binary themselves
cheapo mcp

Flags (HTTP): --http <addr>, --path (default /mcp), --token or $CHEAPO_MCP_TOKEN (bearer auth), --stateless (for proxies/load balancers), --session-timeout (default 30m). Region/locale/stores come from the global flags --country/--locale/--store and apply as defaults for the tool calls.

Tools:

Tool	Purpose
list_offers	Mirrors cheapo list: mode = free (default) / upcoming / deals, plus store, country, locale

Example call:

{"name": "list_offers", "arguments": {"mode": "deals", "store": "steam"}}

The server is stateless: every call returns the complete current state. What counts as "new" is decided by the client — it is the only one that knows what it has already seen. This means no server memory, no state file, and no surprises after a restart.

Responses are structured (MCP structuredContent) with title, store, kind, seller, url, original_price, starts, ends (RFC 3339, absent when the date is unknown), id. Unreachable stores land in warnings instead of failing the call.

Auth & operation: without --token the endpoint is open — in that case only bind to loopback. The token comes via --token, $CHEAPO_MCP_TOKEN or a .env file (CHEAPO_MCP_TOKEN=..., same mechanics as Chatto — existing environment variables take precedence). /healthz answers unauthenticated with {"status":"ok","version":...} for monitoring. Example:

curl http://127.0.0.1:8080/healthz
# MCP client (streamable HTTP): http://127.0.0.1:8080/mcp

Limitations: A long runner that posts on new free games remains cheapo watch or the Chatto daemon (below), not the MCP server — it only answers requests (list_offers covers list; watch has no equivalent).

More platforms

• Steam ✅ done: cheapo list --store steam or --store all. Free-to-keep via HTML scrape of store.steampowered.com/search/?maxprice=free&specials=1, free weekend via store.steampowered.com/api/featuredcategories/ (details: AGENTS.md). With --store you choose epic, steam, gog or all (default).
• GOG ✅ done: cheapo list --store gog. GOG has no public giveaway API; the provider reads the embedded section JSON of the homepage (<script id="gogcom-store-state">, object with endDate + product). Exactly one active giveaway; kind: upcoming if the start period lies in the future.
• Epic "upcoming" ✅ done: cheapo list --upcoming shows announced upcoming free promotions (Epic only; Steam ignores the flag).

More stores — feasibility (as of: Oct 2026)

Store	Feasible without browser/login?	Source
Epic	✅ done	public JSON endpoint freeGamesPromotions
Steam	✅ done	search HTML scrape + featuredcategories JSON API
GOG	✅ done	embedded section JSON of the homepage (gogcom-store-state)
Prime Gaming	⚠️ hard	requires Amazon login (session cookies); reference: vogler (Playwright). No public API.
AliExpress	⚠️ hard	login + quirks (exit code != 0 without coins); only points bonuses, hardly any games
itch.io	✅ feasible	https://itch.io/games/free (HTML scrape); no login for detection
Humble Bundle	⚠️ medium	changing promo structure; no stable free-games JSON, scraping required
Ubisoft Connect	❌	login + client required, no public API

Chatto integration

The package internal/chatto/ is a hand-built ConnectRPC client (JSON codec) for Chatto (tested against 0.5.0-beta.27+): POST {base}/api/connect/chatto.api.v1.<Service>/<Method> with a bearer token. The Chatto Go codebase (github.com/chattocorp/chatto) keeps generated code and handlers under internal/ — not importable from outside, hence the own client. Message schemas come from proto/chatto/api/v1/ of the Chatto repo (field numbers compatible, only the JSON subset is modelled).

CLI commands (credentials deliberately provided by the operator, never fetched automatically):

# .env in the project root (godotenv), never commit it — it is in .gitignore:
CHATTO_TOKEN="<token>"               # set by the operator
# CHATTO_BASE_URL=https://chat.chatto.run   # optional, is the default

cheapo chatto-rooms                     # list rooms (client verification)
cheapo chatto-send --room <room_id>     # post current free games
cheapo chatto-send --room <room_id> --upcoming   # upcoming ones (Epic)

Still open (roadmap): a watch-mode daemon that posts to the chat on new free games (state signature like free-games-notifier); Discord-freestuff-like server-side integration (just an idea).

Architecture

cmd/cheapo/          Cobra CLI (list, watch, mcp; --store epic|steam|gog|all)
internal/game/       Provider-agnostic game type + provider interfaces
internal/providers/  Store selection (epic|steam|gog|all) for CLI and MCP
internal/ops/        List modes (free/upcoming/deals) — shared by CLI and MCP
internal/epic/       Epic client (freeGamesPromotions, public JSON endpoint)
internal/steam/      Steam client (search scrape + featuredcategories API)
internal/gog/        GOG client (homepage section JSON, gogcom-store-state)
internal/chatto/     Hand-built ConnectRPC client (JSON) for Chatto servers
internal/watch/      Polling/eventing across all providers: reports only new games
internal/mcpserver/  MCP tool (list_offers) over HTTP/stdio

Reference: how the original project works

The reference project (vogler/free-games-claimer) automates a real browser with Playwright: login (session cookies, 2FA, captcha handling), detecting the "Free Now" tiles on the store page and clicking through the purchase process. The free games info comes from the same backend JSON that we query directly — details and sources in AGENTS.md.

License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). Copyright (C) 2026 Paul Klumpp. Full text: LICENSE.