subscription-scanner

Subscription Scanner

Scans Gmail for active paid subscriptions and tracks them over time. Surfaces additions / cancellations between scans.

Usage

The scan is agent-driven, not script-driven, because Gmail access lives in the Claude Code MCP layer (not in Python). The proactive-loop or owner-on-demand fires the scan via:

/scan-subscriptions

…or the cron job below invokes the agent with the scan-prompt.md body verbatim.

Files

• scan-prompt.md — the prompt text the agent runs to perform a scan. Updates here propagate via the cron config. Personalize this file before first use — the third Gmail-query line names specific senders tied to one user's actual subscriptions (Apple, Spotify, Anthropic, OpenAI, Netflix, Adobe, GitHub, 1Password, NYT, WSJ, Disney+, Hulu, Tesla insurance, Xfinity, …). Edit the from: list to match your subscriptions, or the scan will miss vendors not on the default list.
• state/subscriptions.json — current list (gitignored — contains personal financial data)
• state/history/<YYYY-MM-DD>.json — snapshots, for diff (also gitignored)

State schema

{
  "last_scan": "ISO8601 timestamp",
  "subscriptions": [
    {
      "vendor": "Apple iCloud+ 2TB",
      "category": "Storage|Streaming|Connectivity|Insurance|Software|Membership|Other",
      "amount": 9.99,
      "currency": "USD",
      "frequency": "monthly|annual|other",
      "account": "a.kunte@gmail.com or family member name",
      "last_charged": "YYYY-MM-DD",
      "next_charge": "YYYY-MM-DD or null",
      "status": "active|cancelled|uncertain",
      "source_sender": "email From: address that established this",
      "notes": "free-form caveats / corrections"
    }
  ],
  "scan_history": [
    {
      "date": "ISO8601",
      "active_count": <int>,
      "added": ["vendor names"],
      "removed": ["vendor names"],
      "amount_changed": [{"vendor": "...", "from": <num>, "to": <num>}]
    }
  ]
}

How /paidsubscriptions reads this

web-client.ts route at /paidsubscriptions:

1. Reads skills/subscription-scanner/state/subscriptions.json
2. Renders a sortable table with vendor, amount, frequency, account, status, last/next charge
3. Highlights diffs from the previous snapshot (scan_history[-1].added in green, removed in strikethrough red)
4. Shows last-scan timestamp at the top
5. Provides a "Scan now" button that POSTs to /paidsubscriptions/scan — that endpoint writes a task file to tasks/ triggering an out-of-cycle scan in the next loop pass

Cron

Monthly: 1st of every month at 08:13 (off-peak minute) — see skills/schedule-crons/crons.json entry subscription-scan.

crons.json is gitignored (per-user), so the entry isn't in this repo. Add it manually after cloning:

{
  "name": "subscription-scan",
  "cron": "13 8 1 * *",
  "prompt": "Run the monthly paid-subscription scan. Read the full instructions in skills/subscription-scanner/scan-prompt.md and follow them verbatim. Update skills/subscription-scanner/state/subscriptions.json with the latest list, snapshot the previous version to state/history/, and write a proactive Telegram notification to results/proactive-{ts}.txt only if subscriptions were added, removed, or had price changes since the previous scan. Stay silent if nothing changed."
}

The cron expression 13 8 1 * * fires at 08:13 on the 1st of every month. Bump to */10 * * * * during development to trigger every 10 min.