Claude Plex Movie Recommender
RealRogerWinter/claude-plex-movie-recommender
Recomendações de filmes inteligentes para Plex com atlas visual interativo
Ver no GitHubSkill do Claude Code que transforma sua biblioteca Plex em um sistema inteligente de recomendações. Escaneia o acervo, pesquisa títulos na web que você não possui mas vai amar, e gera uma página HTML rica com um mapa interativo de proximidade (atlas) onde a distância codifica similaridade de gosto.
Instalação
npx convez-ai RealRogerWinter/claude-plex-movie-recommender1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Descobrir filmes alinhados ao seu gosto baseado na biblioteca Plex existente
- Gerar recomendações personalizadas por usuário via Tautulli
- Visualizar relacionamentos entre títulos em um mapa interativo de proximidade
- Integrar com Overseerr/Jellyseerr para verificar disponibilidade e fazer requisições
- Construir um histórico evolutivo de recomendações que aprende a cada execução
Veredito

Ferramenta sofisticada e bem-arquitetada para curadores de mídia em Plex. Combina inteligência (Claude para análise de gosto) com visualização criativa (atlas D3), mas exige servidor Plex ativo e conhecimento técnico para setup. Ideal para cinéfilos que querem descoberta algorítmica sem deixar o ecossistema Plex.
README
A tradução para o português deste README ainda está na fila.
Claude Code Movie Recommender
A Claude Code skill for Plex servers that turns a Plex library into a living recommendation atlas: it scans the library, researches the web for titles the owner doesn't own but will love, ties every pick back to something already on the shelf (with a one-line why), and publishes a rich HTML page plus an interactive proximity map where closeness encodes taste.
It's stateful: each run diffs the library against the last, learns from what was actually added (a previously-recommended title that reappears is a strong "more like this" signal), evolves the taste profile, and appends a new round of picks instead of overwriting the old ones.
Built for Plex. It reads the Plex library over the Plex API (Tautulli adds per-user tabs; Overseerr/Jellyseerr add availability + requests — both optional). The library backend is pluggable (
library.source), but Plex is the one that's implemented and supported. Everything installation-specific lives in one config file, so the repo stays generic and shareable.

What it produces
index.html— recommendation cards grouped into taste regions (swipeable carousels). Each card: poster, title/year, full overview, IMDb + Rotten Tomatoes links, because you have … links with a one-line why, a freshness badge (which run produced it), and, when Seerr is configured, a live availability badge + one-click request.map.html— a full-screen constellation: every pick and its library anchors as nodes; proximity = similarity; edges = the "because you have X" links.- Per-user tabs (optional, via Tautulli) — a personalized tab per Plex user, driven by their watch history. Selecting a user's tab re-renders the atlas to just their picks (and the titles they anchor to); "Everyone" restores the library-wide map.
data.json— the single data file both pages read (schema:references/data-schema.md).

How it works
scan library → diff vs last run → profile taste → [synthesize a discovery cluster] → research the web
→ enrich (posters/ratings) → explain each link → lay out the map → publish
Each stage is a small, reusable prompt (prompts/01–08) with a strict JSON contract; deterministic Python
scripts handle scanning, diffing, assembly, and deploy; a Workflow script (scripts/pipeline.workflow.js)
fans the research out in parallel.
Requirements
- Python 3 — standard library only, no pip packages to install.
- A Plex server to read — the one hard dependency.
- Claude Code to run the skill; the Workflow tool drives the parallel
research (without it, run the
prompts/by hand). - Optional: a TMDB API key (richer posters/metadata), Tautulli (per-user tabs),
Overseerr/Jellyseerr (live availability + one-click requests), and an SVG rasterizer
(
rsvg-convert/ Inkscape / ImageMagick) to emit a PNG social-card image. D3 loads from a CDN.
Install
Drop this directory in the Claude Code skills folder so it's discoverable as /recommendations:
git clone https://github.com/RealRogerWinter/claude-plex-movie-recommender ~/.claude/skills/recommendations
Configure
Nothing personal is committed. Copy the example config and edit it:
mkdir -p ~/.config/recommendations
cp ~/.claude/skills/recommendations/config.example.json ~/.config/recommendations/config.json
python3 ~/.claude/skills/recommendations/scripts/config.py show # inspect the merged config
Every field is documented in references/configuration.md (resolution
order, env overrides, and how tokens/keys are read at runtime; they're never stored).
Integrations (all optional except Plex)
The skill needs one thing: a library to read. Everything else degrades gracefully; see
references/integrations.md.
| Integration | Adds | If absent |
|---|---|---|
| Plex (required) | the library to scan + posters | nothing runs |
| Tautulli | a personalized tab per user (watch history) | library-wide recs only |
| Seerr (Overseerr/Jellyseerr) | live availability + one-click request & auto-approve | no availability/request UI |
| TMDB key | faster, higher-quality posters/metadata | best-effort public posters |
| Deploy | publish the static site | preview locally only |
Run
cd ~/.claude/skills/recommendations
WD=~/recommendations
python3 scripts/scan_library.py --workdir $WD # snapshot the library
python3 scripts/track_state.py --workdir $WD # diff vs last run, reconcile the ledger
# generate this round's picks via scripts/pipeline.workflow.js (Claude Code Workflow), then:
python3 scripts/build_site.py --workdir $WD --append $WD/work/recommendations.json
python3 scripts/serve.py --dir $WD/site # preview at http://localhost:8000
UI preview (no Plex needed): run
python3 scripts/serve.py --dir assets/templates, then openhttp://localhost:8000/index.html?data=data.sample.jsonto render the bundled sample data.
Daring & Discovery modes
Two optional flags reshape a run (set modes.* in config, or pass daring: true / discovery: true in the
pipeline args):
- daring — pushes past the safe zone: deeper cuts, festival/international, older and formally bold picks.
- discovery — first synthesizes a brand-new taste cluster from the library's genre trends (a novel intersection it doesn't already have), then researches it.
Tag the build with --mode daring / --mode discovery so the round is labelled and cards are badged. After a
bold run, scripts/analyze_runs.py tables every target × mode (availability, era, anchor novelty, thin
picks), so it's clear whether the run explored new ground: the measurement half of the feedback loop.
The feedback loop
scan records everything found; track_state diffs it against last time. Titles the owner added become
taste signal; any that match a prior recommendation are marked acquired (a strong "more of this"). Prompt
07-evolve-preferences folds the diff into the profile so each round explores new ground, and the site's
"Since last time" panel shows what changed. Recommendations accumulate across rounds; a run filter and
freshness badges show which round produced each pick.
Publish
The build is a self-contained static site. See references/deploy.md for GitHub
Pages, Cloudflare (Pages / Tunnel with a Basic-Auth gate), or any static host, including how to wire the
Seerr request proxy. Publishing is public; treat the first publish (and any DNS change) as a deliberate,
confirm-first step. Keep the generated site/ (personal data) out of any repo intended for open-source; the
skill source is the generic, shareable part.
Project layout
prompts/ 01–08 — classify · taste · research · enrich · explain · map · evolve · discovery
references/ configuration.md · integrations.md · deploy.md · data-schema.md · research-sources.md
scripts/ config · plexlib · scan_library · track_state · build_site · seerr · tautulli
request_proxy · analyze_runs · serve · deploy.sh · pipeline.workflow.js
assets/templates/ index.html · map.html · app.css · render.js · map.js · logo.svg · og.svg · favicon.svg
docs/ README screenshots
README.md · config.example.json · SKILL.md · LICENSE
Credits & acknowledgements
- Metadata & posters from The Movie Database (TMDB). This product uses the TMDB API but is not endorsed or certified by TMDB.
- Recommendations are triangulated across editorial lists and community sources — Letterboxd, Trakt,
TasteDive, Reddit, JustWatch, IMDb, Rotten Tomatoes (see
references/research-sources.md). - Constellation rendered with D3; type is Fraunces, Hanken Grotesk, and Space Mono via Google Fonts.
- A skill for Claude Code.
Not affiliated with or endorsed by Plex, TMDB, Overseerr/Jellyseerr, or Tautulli. All film/TV titles, posters, and trademarks belong to their respective owners.
License
MIT.