TVmaze series tracker

Monitor favorite TV / streaming series using the public TVmaze API. No API key. License: data is CC BY-SA — always credit TVmaze (link back via show/episode URLs).

When to use

• “Add Silo / Severance to my shows”
• “What episodes air today / this week?”
• “Alert me the day a new episode drops”
• Building a personal TV watchlist + daily digest for an agent runtime (Hermes, cron, launchd, GitHub Actions, etc.)

API overview

Endpoints used by this skill

Do not use singlesearch to auto-add favorites — homonyms are common. Use /search/shows and human confirmation.

Show objects include image.medium / image.original (poster), summary (HTML), network or webChannel, status, premiered, url.

Episodes include id, season, number, name, airdate (YYYY-MM-DD), airtime, airstamp (ISO-8601), url.

Full endpoint notes: [references/tvmaze-api.md](references/tvmaze-api.md).

Portable script

Bundled CLI (Python 3 stdlib only — no pip deps):

python skills/tvmaze-series-tracker/scripts/tvmaze_tracker.py <command>

Environment (optional):

State files inside TVMAZESTATEDIR:

• shows.json — tracked favorites (id, name, nick, network, imagemedium, url, addedat)
• alerts.json — dedupe map of notified episode.id → air date

Commands

# Search candidates (JSON)
python scripts/tvmaze_tracker.py search "Severance" --limit 5

# Show detail + recent/upcoming episodes
python scripts/tvmaze_tracker.py show 44933

# Favorites
python scripts/tvmaze_tracker.py list
python scripts/tvmaze_tracker.py add 44933 --nick "Severance"
python scripts/tvmaze_tracker.py remove 44933   # or nick / exact name

# Human-facing text
python scripts/tvmaze_tracker.py today              # episodes airing "today" in TVMAZE_TZ_OFFSET
python scripts/tvmaze_tracker.py today --date 2026-07-31
python scripts/tvmaze_tracker.py upcoming --days 14

# Cron entrypoint: print alert only if something airs; empty stdout if nothing
python scripts/tvmaze_tracker.py check
python scripts/tvmaze_tracker.py check --date 2026-07-31 --force

Copy the script into your agent’s scripts directory if the runtime requires a fixed path (e.g. Hermes ~/.hermes/scripts/).

Workflow: add a show (required confirmation)

1. User asks to track a title (“add Silo”).
2. Run search "Silo" --limit 5.
3. Pick the best score; if the name is ambiguous, prepare top 2–3.
4. Reply with a validation card before writing state:

- Title (premiere year · status · network/webChannel · genres) - Short synopsis (strip HTML from summary, 2–4 lines) - Poster: download image.original or image.medium and attach, or embed the URL - TVmaze url - Explicit question: “Is this the one?”

1. Only after explicit yes / “that one” / a chosen TVmaze id:

``bash python scripts/tvmazetracker.py add SHOWID [--nick "Friendly name"] ``

1. Confirm with show SHOW_ID and mention the next known air dates (if any).

Never auto-add from a single search hit without confirmation.

Example validation reply shape

[poster image]

**Silo** (2023 · Running · Apple TV)
Drama · Science-Fiction · Mystery
id: 38052

In a ruined and toxic future, thousands live in a giant silo...

https://www.tvmaze.com/shows/38052/silo

Is this the one you want me to track?

Workflow: daily air-day alert

Goal: notify the user on days when at least one tracked show has an episode (airdate == today in the configured timezone). Stay silent otherwise.

1. Schedule a daily job (example: 0 9 * local morning).
2. Run python scripts/tvmaze_tracker.py check.
3. Delivery rules for agent/cron runtimes:

- Non-empty stdout → send as the user message (markdown ok). - Empty stdout → do not message (no “nothing today” spam). - Prefer no LLM on the cron path when the script already formats the text (saves tokens, avoids drift).

1. Dedupe: check records each episode.id in alerts.json so the same episode is not re-alerted. Use --force only for tests.

Sample alert output

📺 Series today — Friday 31 Jul

• **Silo** (Apple TV) — S03E05 _Memory_ · 21:00
  https://www.tvmaze.com/episodes/...

_Source: TVmaze_

Hermes / similar agent notes

• Store state under a durable path (e.g. $HERMESHOME/state/tvmaze/) via TVMAZESTATE_DIR.
• Register a no_agent cron whose script only runs check and prints to stdout.
• Cron --script flags often disallow absolute paths — place a thin wrapper next to other agent scripts.

Other schedulers

• cron/systemd timer: same check + notify bridge only if stdout non-empty.
• GitHub Actions: schedule workflow; post to Slack/Discord when step output is non-empty.
• launchd / Task Scheduler: identical contract.

Other user intents

Pitfalls

• Homonyms: e.g. multiple “Silo” entries — always confirm with poster + year + network.
• Streaming: airdate is reliable for “day it drops”; airtime may be null — script falls back to airstamp converted with TVMAZETZOFFSET.
• Missing future eps: TVmaze may not have next-season dates yet → upcoming empty is normal; keep the show tracked.
• Specials: default episode list omits specials; use API specials=1 only if the user wants them (extend script if needed).
• Timezone: “today” is defined by TVMAZETZOFFSET, not the host UTC date alone.
• Rate limits: small gaps between per-show episode fetches; on 429 sleep and retry.
• Attribution: keep “Source: TVmaze” (or equivalent) on user-facing digests.

Quick curl cheatsheet

curl -sS -A "my-agent/1.0" "https://api.tvmaze.com/search/shows?q=Severance"
curl -sS -A "my-agent/1.0" "https://api.tvmaze.com/shows/44933"
curl -sS -A "my-agent/1.0" "https://api.tvmaze.com/shows/44933/episodes"
curl -sS -A "my-agent/1.0" "https://api.tvmaze.com/schedule/web?date=2026-07-31"

Related

• Official docs: https://www.tvmaze.com/api
• This skill’s API digest: [references/tvmaze-api.md](references/tvmaze-api.md)
• Script: [scripts/tvmazetracker.py](scripts/tvmazetracker.py)