OverSnitch/README.md

OverSnitch

A self-hosted dashboard for monitoring Overseerr/Jellyseerr users — who's requesting, how much storage they're consuming, how often they actually watch what they request, and whether anything needs your attention.

Built with Next.js 16, TypeScript, and Tailwind CSS.

---

Features

• Leaderboard — per-user request count, total storage, average GB per request, and optional Tautulli watch stats (plays, watch hours), each ranked against the full userbase
• Alerting — automatic alerts for stalled downloads, neglected requesters, and abusive patterns, with open/close state, notes, and auto-resolve when conditions clear
• SWR caching — stats are cached server-side for 5 minutes and seeded from localStorage on the client, so the dashboard is instant on return visits

---

Setup

1. Clone and install

git clone https://gitea.thewrightserver.net/josh/OverSnitch.git
cd OverSnitch
npm install

2. Configure environment

Create .env.local in the project root:

# Required
SEERR_URL=http://overseerr:5055
SEERR_API=your_overseerr_api_key

RADARR_URL=http://radarr:7878
RADARR_API=your_radarr_api_key

SONARR_URL=http://sonarr:8989
SONARR_API=your_sonarr_api_key

# Optional — enables watch time stats and ghost/watch-rate alerts
TAUTULLI_URL=http://tautulli:8181
TAUTULLI_API=your_tautulli_api_key

# Optional — if your services use self-signed certs
# NODE_TLS_REJECT_UNAUTHORIZED=0

3. Run

npm run dev                      # development
npm run build && npm start       # production

---

Alerts

Alerts are generated on every stats refresh and persisted in data/alerts.json (gitignored). They have two states — Open and Closed — and can be manually closed with a per-category cooldown, or auto-resolved when the underlying condition clears.

Content alerts

These are keyed per piece of media, not per user. If multiple users requested the same item, they're grouped into a single alert.

---

Not Downloaded

A movie or TV show was approved but no file exists in Radarr/Sonarr.

Parameter	Default	Description
UNFULFILLED_MIN_AGE_DAYS	3	Minimum days since approval before alerting. Prevents noise on brand-new requests.

• Skipped entirely if Radarr reports isAvailable: false (unreleased) or Sonarr reports status: "upcoming".
• Auto-resolves when the file appears (i.e. sizeOnDisk > 0).
• Manual close cooldown: 3 days.

---

Incomplete Download

An ended TV series has been partially downloaded (less than 90% of episodes on disk).

Parameter	Default	Description
UNFULFILLED_MIN_AGE_DAYS	3	Same minimum age as above.
Completion threshold	90%	Series below this are flagged. Hardcoded.

• Only fires for series with status: "ended" in Sonarr. Continuing shows are excluded because missing episodes may simply not have aired yet.
• Percentage is calculated as episodeFileCount / totalEpisodeCount, not Sonarr's percentOfEpisodes (which counts against monitored episodes only and would be inaccurate here).
• Auto-resolves when completion reaches 90%+.
• Manual close cooldown: 3 days.

---

Pending Approval

A request has been sitting unapproved for too long.

Parameter	Default	Description
PENDING_MIN_AGE_DAYS	7	Minimum days a request must be pending before alerting.

• One alert per request item, not per user.
• Skipped if the content is unreleased (same availability checks as above).
• Auto-resolves when the request is approved or declined.
• Manual close cooldown: 3 days.

---

User behavior alerts

These fire once per user. Ghost Requester takes priority over Low Watch Rate — a user will only ever have one behavior alert open at a time. Both require the user to be "established" (at least one request older than USER_MIN_AGE_DAYS) to avoid flagging new users.

Requires Tautulli to be configured (except Frequent Declines).

Parameter	Default	Description
USER_MIN_AGE_DAYS	14	Days since oldest request before a user is eligible for behavior alerts.

---

Ghost Requester

A user has made several requests but has never watched anything on Plex.

Parameter	Default	Description
MIN_REQUESTS_GHOST	5	Minimum total requests before flagging.

• Manual close cooldown: 14 days.

---

Low Watch Rate

A user watches a small fraction of what they request.

Parameter	Default	Description
MIN_REQUESTS_WATCHRATE	10	Minimum requests before the ratio is considered meaningful.
LOW_WATCH_RATE	0.2	Ratio of plays / requests below which an alert fires (default: under 20%).

• Manual close cooldown: 14 days.

---

Frequent Declines

A user has had multiple requests declined in a rolling window.

Parameter	Default	Description
MIN_DECLINES	3	Minimum declined requests in the lookback window.
DECLINE_LOOKBACK_DAYS	60	Rolling window in days.

• Does not require Tautulli.
• Manual close cooldown: 14 days.

---

System alerts

No Tautulli Watch Data

Tautulli is configured but no plays matched any Overseerr user.

This usually means emails don't align between the two services. Check that users have the same email address in both Overseerr and Tautulli (or that display names match as a fallback).

• Manual close cooldown: 1 day.

---

Alert lifecycle

Condition detected
       │
       ▼
    [OPEN] ◄──────────────────────────────────────┐
       │                                           │
  ┌────┴───────────────┐             Cooldown      │
  │                    │              expires      │
  ▼                    ▼                           │
Condition          Manually                        │
clears             closed                          │
  │                    │                           │
  ▼                    ▼                           │
[AUTO-RESOLVED]    [CLOSED] ──── Condition ────────┘
 no cooldown        cooldown      returns after
 reopens            suppresses    cooldown
 immediately        re-open

• Auto-resolved alerts have no cooldown and will reopen immediately if the condition returns.
• Manually closed alerts suppress re-opening for a category-specific number of days (see cooldowns above).
• Reopening a manually closed alert via the UI clears the cooldown immediately.