User Guide

User Guide

Installing

Option A — Download the release (easiest)

Grab the latest from Releases:

• PokeTrack_<version>_x64-setup.exe — the native Tauri desktop installer (recommended). Per-user install, no admin rights, no Python required. See Desktop Shell for how it works.
• PokeTrack.exe — the original standalone CustomTkinter desktop app, also no Python required. Still published alongside the installer.
• Source code (zip) — if you'd rather run it with Python (see Option B); also required for the web app, since neither desktop build includes a standalone web server you'd run separately.

Option B — Run from source

Requires Python 3.10+ (tested on 3.13 and 3.14).

git clone https://github.com/SpaceSquare640/PokeTrack-App.git
cd PokeTrack-App
pip install -r requirements.txt

A virtual environment avoids interpreter mix-ups if you have multiple Python installs:

python -m venv .venv
.venv\Scripts\activate      # Windows; use `source .venv/bin/activate` on macOS/Linux
pip install -r requirements.txt

Pillow (thumbnails) and plyer (desktop notifications) are optional — the app runs fine without them, just missing that one feature.

Running

Desktop app

python main.py

Web app

python run_web.py
# then open http://127.0.0.1:5000/

The desktop app's "Open Web View" button launches the web server for you and opens your browser — you don't need to run both manually.

On first launch the event list is briefly empty while the initial fetch runs in the background; it fills in automatically within a few seconds.

Using the app

Browsing events

• Cards show a thumbnail, event type, region, start/end time, and a live countdown ("Starts in 3h" / "Ends in 2d") that ticks continuously.
• Click a card (or View Details) to open the full event page — description, featured raid bosses, promo codes, and spawn/research flags when present. Bosses that can appear shiny are marked with ✨.
• The stats bar shows live / upcoming / total counts for your current filter.

Search & filters

• The search box filters by name/heading instantly (no page reload on the web UI).
• The type dropdown narrows to one event type (Community Day, Raid Battles, …).
• Region filter: pick the regions you care about; Global events always show regardless of your selection. See Configuration for how region inference works.

Favorites

Click the star (☆/★) on any card or the detail page to favorite that event type (not a single event — e.g. favoriting one Community Day favorites all Community Days). Use the Favorites toggle to filter to only starred types, and optionally set "notify only for favorites" in Settings so alerts don't fire for event types you don't care about.

Calendar export

• Per event: the detail page has an Add to Calendar (.ics) link.
• Filtered: the Calendar (.ics) button on the dashboard exports whatever your current search/type/region/favorites filter shows.
• Subscribe (web only): /calendar.ics is a live feed URL — point your calendar app's "subscribe by URL" at it (optionally with ?q=, ?type=, ?fav=1 query params) to get updates automatically. See Web API.

Notifications

PokéTrack can alert you through multiple channels when new events appear in your selected regions — desktop notifications, a webhook (Discord/Slack/ custom), and Telegram. All are configured in Settings; see Configuration for the full reference and setup steps.

Event reminders

Independent of the new-event notification above, PokéTrack can also remind you before an event starts — a desktop/webhook/Telegram alert fires once, a configurable number of minutes ahead (default 15; set to 0 to turn it off). Set the lead time in Settings; see Configuration.

Theme

Switch between light and dark from Settings — both interfaces share the same palette source, so desktop and web always match. The web UI persists your choice and applies it before first paint (no flash of the wrong theme).

Language

Switch languages from the header dropdown (desktop) or the language selector (web) — English, Traditional Chinese, Simplified Chinese, Japanese, Korean. The whole UI (including the composed event descriptions) re-renders immediately.

Settings tab / page

Covers: webhook URL + secret, notifications on/off, notify-favorites-only, event reminder lead time, Telegram bot token + chat ID, 12h/24h time format, display timezone, theme (light/dark), data source (ScrapedDuck vs. the official blog fallback), refresh interval, and config import/export (back up or move your settings between machines/UIs).

System tray (desktop)

If close_to_tray is enabled in Settings, closing the window minimizes to the system tray instead of quitting — right-click the tray icon for Show / Refresh / Quit. (Applies to the legacy CustomTkinter app; the Tauri shell's native tray integration is tracked in Desktop Shell.)

Install the web app / use it offline (PWA)

The web app is an installable Progressive Web App: your browser will offer an "Install" / "Add to Home Screen" option, and once installed it works offline — a service worker caches the app shell and the last-seen event data, so you can still browse previously-loaded events without a connection. Running it this way still needs no Node or build step; it's a progressive enhancement on top of the normal web app.

Update notifications

A best-effort check against GitHub Releases runs at startup and every 6 hours. When a newer release is available, the desktop app shows a clickable footer badge and the web app shows a top banner — both open the release page. Nothing shows when you're already up to date, and the check fails silently if GitHub is unreachable.

Footer

Both interfaces show a persistent footer with links to the maintainer's GitHub profile and Discord community, plus a credit line.

Troubleshooting

Symptom	Explanation
Empty list right after launch	Normal — the first background fetch takes a few seconds.
"Showing cached data" message	The feed was unreachable; your last successfully-fetched events remain visible.
Feed consistently unreachable	Switch Source to "blog" (official Pokémon GO news page) in Settings as a fallback — it has fewer structured details but doesn't depend on the ScrapedDuck mirror.
ModuleNotFoundError on launch	You likely installed dependencies into a different Python interpreter than the one you're running with — see the venv steps above.

See also: Configuration for settings reference, and Legal & Disclaimer for data-source and trademark notices.