seerrcompanion

A small companion service for Seerr that watches what users request and what they actually watch.

1. Unwatched requests are marked for deletion. If a user requests a series, does not watch it, and then requests another title (series or film), the earlier series is marked for deletion and a notification is sent through Apprise.
2. Multi-season requests are trimmed to the first season. If a user requests several seasons, the request is changed to the lowest requested season. buffarr fills in the rest as they watch.

Setup

docker run -d --name seerrcompanion -v /mnt/user/appdata/seerrcompanion:/config \
  -e SEERR_URL=http://seerr:5055 -e SEERR_API_KEY=... \
  -e TAUTULLI_URL=http://tautulli:8181 -e TAUTULLI_API_KEY=... \
  -e APPRISE_URLS='discord://...' -e WEBUI_USERNAME=admin -e WEBUI_PASSWORD=... -p 8080:8080 ghcr.io/poag/seerrcompanion:latest

docker exec seerrcompanion seerrcompanion flagged lists what is currently marked for deletion.

Web UI

With WEBUI_USERNAME and WEBUI_PASSWORD set, the container serves a review page on port 8080 listing everything marked for deletion, with Keep and Delete per title (Delete asks for confirmation and removes the files and the media entry through Seerr). Kept titles are never flagged again. A history table shows past outcomes.

The Requests tab lists every request in Seerr (filter: all, pending, approved, declined, not watched, flagged; 50 per page) with the requester, seasons, request status, availability and watch state. Watch state is only shown for approved, available titles: watched, not watched, or unknown when the Plex ratingKey or Tautulli user cannot be resolved. The poller builds this each cycle, so loading the page never calls Seerr or Tautulli; a watched result is kept, while anything else is re-checked every 15 minutes. Each row has a checkbox (plus select-all for the page) and a Delete selected button that, after a confirmation, deletes the selected titles' files (when they have any) and their Seerr media entry, which also removes their requests. Only titles currently listed can be deleted, at most 100 per action, and it is refused in dry run. Deleting a title that was marked for deletion records it as purged.

The first load after a restart shows a loading message until the first poll completes. Sessions last 7 days in a SameSite=Strict cookie, forms carry a CSRF token, and five failed logins from one address locks that address out for five minutes. It serves plain HTTP, so put it behind HTTPS (reverse proxy or Tailscale) before exposing it beyond your LAN. Behind a proxy all clients share the proxy's address, so the lockout applies to everyone at once.

Behaviour you need to know

• Season trimming needs requests to be pending. Seerr only lets you edit a pending request (409 otherwise), and once a request is approved Sonarr has already grabbed every season. So users must not have auto-approve; the companion trims then approves (APPROVE_AFTER_TRIM). Already-processed multi-season requests are logged once and left alone. Season 0 (specials) is dropped when other seasons are requested.
• "Marked for deletion" is state in the companion's own database plus a notification. Seerr has no tag or flag for this. Flags clear automatically (with a notification) if the user watches the title later.
• Only series are flagged, judged against the user's immediately preceding request (series or film). Another season of the same series does not count as another title.
• A title is only judged once it is available in Seerr. If a user requests something new before the previous series finished downloading, the previous one is not judged.
• Never flags on uncertainty. If the Plex ratingKey or the Tautulli user cannot be found, the request is skipped with a warning.
• First live run baselines all existing requests as seen, so history is not mass-flagged. DRY_RUN uses an in-memory store and no baseline, so it previews against your whole history.
• With Tautulli, "watched" means any play of the title (any episode of a show) by that user after the request was created. Seerr's fallback has no timestamps and means "ever watched by this user".