A Claude Code plugin for Plex

Your Plex server,
explained.

Ask Claude about your media library, your server and who's been watching. Cinemetric gathers the numbers and Claude explains them in plain English. Nothing on your server is ever changed.

/plugin marketplace add jeremehancock/cinemetric
/plugin install cinemetric@cinemetric
Set up Cinemetric

setup

Connect in a minute. No token wrangling.

Cinemetric uses Sign in with Plex, the same approval screen other Plex apps use. You approve it in your browser, pick a server and you're done.

  • Your token goes straight from Plex into a private file on your computer. It never appears in the chat.
  • Lists every server your account can use and tests each address, preferring local, encrypted ones.
  • Optionally adds Tautulli for richer watch stats, without the API key passing through the chat either.
  • Shows up in Plex under Authorized Devices, so you can revoke it any time.

Ask Claude: Set up Cinemetric

Claude Code
> Set up Cinemetric
⏺ Open this link, sign in to Plex if asked, and
  approve Cinemetric. Then tell me when you're done.

  Sign in with Plex (expires in 30 minutes)

> done
⏺ Your Plex account can use 2 servers:
  1. Media NAS (yours)
  2. Cabin Mini (shared with you)
  Which one should I use?

> 1
⏺ Connected to Media NAS at a local,
  encrypted address. You can ask for a library
  report now.

  You can revoke access any time in Plex under
  Settings → Authorized Devices ("Cinemetric").
Example reply with made-up data. Claude's wording will vary.

library-report

Know exactly what's on the shelf.

A full picture of every library: how much you have, how much space it takes and what quality it's in, plus the little things that need tidying up.

  • Item counts and storage used, per library and in total.
  • Quality breakdowns: 4K, 1080p and lower, video and audio codecs, and 10-bit video.
  • What was added recently, and how much was added each month: items and storage.
  • Housekeeping: unmatched items, missing posters, unavailable files and very large files.
  • Duplicates: titles with more than one copy, or in more than one library, and the space the extras use.
  • Upgrade candidates: titles only in SD or 720p, skipping any you already have in better quality.
  • Music: how much is lossless or lossy, lossy bitrates, mixed albums, and albums or artists missing artwork.

Ask Claude: Give me a Plex library report, What's been added to Movies recently?, Do I have any duplicate movies?, Which movies are worth upgrading? or How fast is my library growing?

Claude Code
> Give me a Plex library report
⏺ Media NAS (Plex 1.41.1) has 4 libraries:
  9,412 items using 42.1 TB.

  Per library
  
LibraryItemsSize4K
Movies1,28418.6 TB24%
TV Shows6,93021.1 TB9%
Music1,1502.3 TB–
Home Videos38100 GB0%
Movies are mostly HEVC; 455 files are 10-bit. Recently added • The Long Voyage, Paper Lanterns (Movies) • Harbor Lights S2E6 (TV Shows) Worth a look • 1 file Plex can't find on disk, usually a moved file or a drive that isn't mounted. • 7 unmatched items with no proper metadata. • 3 movies are missing posters. • 12 movies have a second copy, using 310 GB. Most are 4K + 1080p pairs, often kept on purpose for streaming. • 41 movies are only in SD or 720p, mostly older titles, plus 3 TV shows (212 episodes) that might be worth upgrading. Observations • About 60% of your TV is H.264; converting it to HEVC would save space.
Example reply with made-up data. Claude's wording will vary.

server-health

A checkup for your server, on demand.

See how Plex is doing right now and what deserves a look, from available updates to why someone's stream is buffering.

  • Version and available updates, and whether remote access works.
  • CPU and memory use.
  • Who's streaming right now: direct play or transcode, and how much bandwidth.
  • Streaming settings, like hardware transcoding and your remote streaming limit.
  • Running tasks (and any that look stuck), library scan freshness and scheduled maintenance, with anything off flagged for you.

Ask Claude: How's my Plex server doing? or Why is Plex transcoding?

Claude Code
> How's my Plex server doing?
⏺ Mostly fine, but there's a Plex update waiting.

  Server
  • Media NAS · Plex 1.41.1 on Linux
  • Update available: 1.41.2
  • Remote access: working
  • CPU 38% (avg 31%) · memory 52% (avg 51%)

  Right now: 2 streams, 14.2 Mbps
  1 direct play, 1 transcode
  Hardware acceleration on · remote
  streams limited to 20 Mbps each
  • alex · The Long Voyage · Living Room TV
    Direct play · 64%
  • sam · Harbor Lights S2E5 · Pixel 9
    Transcode (hardware) · 22%

  Background
  • Nothing running. Movies and TV were
    scanned 3 hours ago.
  • Maintenance runs 02:00–05:00.

  Worth a look
  • Plex 1.41.2 is out. Updates bring fixes
    and security patches.
Example reply with made-up data. Claude's wording will vary.

watch-activity

See what everyone's been watching.

Who's watching right now, plus plays, watch time, favourites and habits over the last 30 days, or any period you ask about.

  • Who's watching right now, on which device, and how far along they are.
  • Total plays and watch time.
  • Most watched movies, shows and music.
  • Most active users and the devices they use.
  • Daily trends and recent plays.
  • The most streams at once, and titles started but never finished.
  • Everyone, or just one person.
  • Uses Tautulli if you have it; otherwise Plex's own history (which counts plays only).

Ask Claude: What's been watched on Plex this month?, Who's watching right now? or What has Sam watched lately?

Claude Code
> What's been watched on Plex this month?
⏺ Watching now
  • jordan: Harbor Lights S03E04 on Living Room
    TV, playing, 40% in
  • sam: The Long Voyage in Chrome, paused

  In the last 30 days, 6 people watched 486
  things for 311 hours.

  What got watched (TV 301 · movies 112 · music 73)
  
Top showsPlaysHours
Harbor Lights6451
Quiet Hours4131
North of Nowhere2925
Top movie: The Long Voyage (9 plays, 18 hours) Who watched • alex 162 plays (104 h), sam 121 (83 h), jordan 88 (57 h) • Mostly on Roku, then Android and Chrome • Busiest moment: 4 streams at once Trend A little busier lately (255 plays vs 231 in the first half); weekends are the peaks. Observations • Most plays are TV. • alex and sam account for 60% of watch time.
Example reply with made-up data. Claude's wording will vary.

users-and-shares

Know exactly who can see what.

Everyone your server is shared with, in one place, instead of one person at a time in Plex's settings.

  • Friends, Plex Home members, managed users and pending invites.
  • Which libraries each person can see, and who can see each library.
  • Who can download, who has content restrictions, and when each person last played something.
  • Which shared libraries the people who can see them actually play from.
  • Flags old invites, people who haven't watched in months, shared libraries nobody has played from lately, and "all libraries" shares.
  • Reads the share list from your plex.tv account (read-only). Never shows anyone's email address.

Ask Claude: Who have I shared my Plex server with? or Who can see my Kids library?

Claude Code
> Who have I shared my Plex server with?
⏺ Your server is shared with 7 people, and
  one invite is still waiting.

  People
  • Plex Home: sam (all libraries, last
    played today), jordan (Movies, TV Shows,
    2 days ago)
  • Managed: Kids (Movies, rated G/PG only)
  • Friends: alex (Movies, TV Shows, can
    download, 3 days ago), riley (Movies,
    5 months ago), and 2 more
  • Pending: casey, invited 6 weeks ago

  Libraries
  
LibraryPeople
Movies7
TV Shows5
Music2
Home Videos1 (only sam)
Worth a look • casey hasn't accepted after 6 weeks; you could resend or cancel the invite. • riley hasn't played anything in 5 months. • sam has "all libraries", so any library you add later is shared with them too.
Example reply with made-up data. Claude's wording will vary.

unwatched

See where your space goes, and whether anyone uses it.

Movies and shows that have sat for months without anyone finishing them, largest first. Just the facts: it never tells you what to delete.

  • Titles added more than 6 months ago that nobody has finished since (or any number of months you ask for).
  • How much space each one uses, when it was added, and when it was last finished, or never.
  • Totals per library and the share of your storage they take up.
  • Counts plays by everyone on your server, not just you. Only finished plays count.
  • Uses Tautulli if you have it; otherwise Plex's own watch history.

Ask Claude: What on my Plex server has nobody watched in months? or Which shows has nobody finished this year?

Claude Code
> What on my Plex server has nobody watched in months?
⏺ 214 titles added more than 6 months ago
  haven't been finished by anyone since
  April 5. Together they use 3.8 TB, about
  10% of your 39.8 TB of movies and TV.

  By library
  
LibraryTitlesSizeNever finished
Movies1681.9 TB121
TV Shows461.9 TB18
Largest
TitleSizeLast finished
Northern Static (52 eps)412 GBnever
Glass Orchard (2019)88 GBMar 2024
The Salt Road (2016)74 GBnever
Lanterns (31 eps)69 GBAug 2023
…and 210 more; ask if you'd like the full list. About the history Plays come from Tautulli and include everyone on your server, going back to March 2022. Partly watched titles still count as not finished, and plenty of titles are kept on purpose.
Example reply with made-up data. Claude's wording will vary.

what-to-watch

Find something good to watch tonight.

A friendly pick from your own library, not a catalog. Say what you're in the mood for and get a few suggestions, each with a reason.

  • Filter by genre, length, decade, rating or content rating, or just ask for something you haven't seen.
  • Shuffled every time, so asking again gives fresh ideas.
  • Pick up where you left off: what you're partway through and the next episode up.
  • Only titles already on your server, never suggestions from somewhere else.
  • "Haven't seen" means your own account's watch status in Plex.

Ask Claude: Find me a comedy under 2 hours I haven't seen or Pick up where I left off

Claude Code
> Find me a comedy under 2 hours I haven't seen
⏺ Here are four comedies under 2 hours
  you haven't watched yet:

  Paper Lanterns (2014, 1h 38m)
  A road-trip comedy about two sisters
  and one very old van. Audience rating
  8.1, the best rated of the bunch.

  The Late Shift (2009, 1h 31m)
  Night-shift cooks, one disastrous
  week. Short and silly.

  Marigold & Sons (1987, 1h 44m)
  An 80s family comedy, if you want
  something everyone can watch. You have
  it in 4K too.

  Low Tide (2021, 1h 26m)
  A beach-town comedy you started but
  didn't finish.

  That's 4 of 212 matches. Want more, or
  a different mood?
Example reply with made-up data. Claude's wording will vary.

show-progress

Know where everyone is in every show.

Follow each person through a series, not just single plays: who's caught up, who has new episodes waiting, and which shows people stopped partway through.

  • Each person's place in a show: the furthest episode they finished, how many are left and what's next.
  • Caught up, new episodes waiting, partway through, or stopped (nothing played in 3 months, or any number you choose).
  • Rewatching early episodes or starting at season 3 doesn't count as falling behind.
  • Which shows got new episodes lately, and whether the people following them have watched them.
  • Uses Tautulli if you have it; otherwise Plex's own watch history.

Ask Claude: Where is everyone in our shows? or Which shows did people stop watching partway through?

Claude Code
> Where is everyone in our shows?
⏺ Across 23 shows, people are partway
  through 9, caught up on 6, have new
  episodes waiting on 3, and stopped
  partway through 5.

  Recently watched
  
ShowWhoAtStatus
Northern StaticsamS02E055 left
Northern StaticalexS01E02stopped Jan
LanternsjoS03E083 new
The Salt RoadalexS01E06caught up
Quiet HarborjoS01E037 left
…and 18 more shows; ask about any one. New episodes nobody has watched Lanterns season 4 (3 episodes, added May 20): jo was following it and hasn't started them yet. About the history Plays come from Tautulli, going back to March 2022. "Caught up" means with what's on your server.
Example reply with made-up data. Claude's wording will vary.

changes

See what changed since last time.

Each time you ask what changed (or build the dashboard), Cinemetric saves a small snapshot on your computer. The next time, on another day, it tells you what arrived, what went missing and who got access since then.

  • Titles added and removed in each library, and new episodes by show.
  • Files Plex can no longer find, and ones that came back.
  • Plex updates, remote access changes, and people given or losing access.
  • The library, server and sharing reports and the dashboard show the same "since last time" changes.
  • Nothing runs in the background: a snapshot is only saved when you ask. Ask a week apart and you see the whole week.
  • Snapshots stay private on your computer, hold no emails or watch history, and are deleted after 90 days.

Ask Claude: What changed on my Plex this week? or Did anything go missing from Plex?

Claude Code
> What changed on my Plex this week?
⏺ Since last Tuesday: 9 new movies,
  23 new episodes, and Plex updated
  itself to 1.41.2.

  Library
  
LibraryAddedRemovedSize
Movies91+212 GB
TV Shows23 eps0+96 GB
New movies include Glass Orchard (2019), The Salt Road (2016) and Paper Lanterns (2014). Most new episodes are Northern Static (12) and Lanterns (8). 4 episodes of Low Tide can't be found now. That usually means a drive wasn't mounted, or files were moved outside Plex. Server Plex went from 1.41.0 to 1.41.2. People jordan accepted your invite, and riley can now see Kids Movies.
Example reply with made-up data. Claude's wording will vary.

episode-gaps

Spot the episodes that slipped through.

Finds the holes in your TV shows using only what's on your server: an episode missing between two you have, a season that starts late, a season missing between others.

  • E01, E02 and E04 are there? It points out E03.
  • Seasons that start late, seasons missing in the middle, and episodes whose files Plex can't find.
  • Specials, files holding two episodes and shows numbered straight on across seasons aren't counted as gaps.
  • Honest about its limits: it can't see episodes after the last one you have, because it never asks an online service.
  • Just the facts: it never tells you where to get anything.

Ask Claude: Am I missing any episodes on Plex? or Is anything missing from Lanterns?

Claude Code
> Am I missing any episodes on Plex?
⏺ 6 of your 212 shows have gaps: 19
  episodes are missing between ones you
  have, one season is missing, and Plex
  can't find the files for 4 episodes.

  Shows with gaps
  Northern Static: S02E04 to E09, and
    S03E01 to E02 (season 3 starts late)
  Low Tide: S01E05 to E08 (Plex can't
    find the files)
  Copper Coast: S01E01 to E03
  Lanterns: season 5, S04E11, and
    S06E02 to E03
  The Night Ferry: S01E07 to E08
  Field Notes: S02E03

  Worth knowing
  Only gaps between the episodes you have
  can be found. If a season ends early or
  a newer season is out, that can't be
  seen. 2 shows only have their later
  seasons, which isn't counted as a gap.
Example reply with made-up data. Claude's wording will vary.

playback-check

Find out why Plex keeps transcoding.

Checks every movie and episode for the usual reasons a file gets converted on the way to your TV, and with Tautulli, shows which devices and people it really happens to.

  • Image-based subtitles (PGS, VobSub), which make Plex redraw the whole picture while subtitles are on.
  • TrueHD and DTS audio that many TVs and streaming sticks can't play, and whether a file has a common track to switch to.
  • Files above your server's remote streaming limit, or a speed you choose.
  • With Tautulli: the devices and people transcoded most, how often, and why.
  • Says "likely", not "will", and never tells you to convert your files.

Ask Claude: Why does Plex keep transcoding? or Which movies won't play directly on my Roku?

Claude Code
> Why does Plex keep transcoding?
⏺ Of your 9,942 files, 1,023 are likely
  to be converted on some devices.

  Why
  628 have image-based subtitles: Plex
    redraws the picture while they're on.
  516 have TrueHD or DTS audio: only the
    sound is converted, which is light.
  177 are above your 12 Mbps remote limit.

  Movies
  The Long Voyage: English subtitles are
    image-only, DTS-HD MA audio
  Harbor Lights: TrueHD audio, has an
    AC3 track to switch to

  Last 90 days
  64 of 1,146 plays were transcoded.
  Living Room (Plex for Roku): 23 of 41,
    mostly for subtitles
  sam: 27 of 96, mostly for subtitles

  Worth knowing
  These are likely causes, not a promise:
  each device plays different things.
Example reply with made-up data. Claude's wording will vary.

subtitles-and-languages

Find the films nobody can follow.

Checks the language of every audio and subtitle track, so you find the foreign film with no subtitles you can read before movie night, not during it.

  • Movies and episodes with audio in another language and no subtitles in yours.
  • For TV, which episodes, such as S02E04 to E07, so you can go straight to the files.
  • Titles missing subtitles in a language you name, such as Spanish for family visiting.
  • Tracks with no language set, which stop Plex picking the right one.
  • How many files have audio and subtitles in each language.
  • Forced subtitles, which usually cover only a few lines, aren't counted as full subtitles.

Ask Claude: Which foreign films can't we follow? or Which movies are missing Spanish subtitles?

Claude Code
> Which foreign films can't we follow?
⏺ I checked against English, your
  libraries' language. Of your 9,942
  files, 17 have audio in another
  language and no English subtitles.

  Foreign audio, no subtitles
  Mountain Spirits (1994): Japanese
    audio, French subtitles only
  The Quiet Garden (2019): Korean audio,
    only forced English subtitles, which
    usually cover just a few lines
  Northern Lines: 9 of 22 episodes,
    Korean audio: S02E04 to E07,
    S03E02 to E06
  Coastal Patrol: 6 episodes labelled
    German, maybe dubbed copies:
    S01E03 to E08

  Language not set
  212 episodes have tracks with no
  language, so Plex may pick the wrong
  one. Most are in Station Days. Ask
  and I'll list the episodes.

  Worth knowing
  This goes by each track's language
  label, which can be wrong or missing.
Example reply with made-up data. Claude's wording will vary.

title-lookup

Everything about one title, in one answer.

Ask about a movie, a show or a single episode and get what Cinemetric knows about it: its files and quality, whether it's likely to transcode, and who watched it.

  • Each version's resolution, HDR, codecs and size, and the libraries it's in.
  • Likely transcode causes for each file, by the same rules as playback-check.
  • For a show: seasons, episode counts, sizes, and episodes whose files Plex can't find.
  • Who watched it, how often, when, and how far they got.
  • Several titles match? Claude asks which one you meant instead of guessing.

Ask Claude: Tell me about Harbor Lights on my Plex or Who's watched Lanterns S02E03?

Claude Code
> Tell me about Harbor Lights on my Plex
⏺ Harbor Lights (2019) is a 1 h 45 min
  PG-13 drama in your Movies library,
  added 17 July 2024. It's in your Sea
  Stories collection.

  Files
  4K HDR, HEVC 10-bit, TrueHD 7.1 audio,
    58.0 GB
  1080p, H.264, AC3 5.1 audio, 12.0 GB

  Playback
  The 4K file's TrueHD audio is likely
  to be converted on many TVs and sticks
  (just the sound, which is light). The
  1080p file should play directly on
  most devices.

  Watching
  Played 3 times by 2 people. alex
  finished it on 2 October; sam stopped
  at 40%.

  Worth knowing
  These are likely causes, not a promise:
  each device plays different things.
Example reply with made-up data. Claude's wording will vary.

collections-and-playlists

See how your library is grouped.

Every collection and playlist on your server, how big each one is, and the ones that have quietly gone thin or broken.

  • Each collection's titles and storage, largest first, smart or regular.
  • Collections with only one title, and empty ones.
  • How much of each library isn't in any collection.
  • Your playlists with their length and size.
  • Playlist items whose files Plex can no longer find.
  • Plex keeps playlists per account, so it lists only your own.

Ask Claude: What collections do I have on Plex? or Do any of my playlists have missing files?

Claude Code
> What collections and playlists do I have?
⏺ You have 48 collections (31 smart)
  and 5 playlists. 3 collections hold
  just one movie, and one playlist has
  items Plex can't find.

  Largest collections
  Sea Stories      42 titles   610 GB
  Silent Classics  27 titles   188 GB
  Lanterns (TV)     4 shows    402 GB

  One title only
  Keaton: only The General (1926)
  Night Owls: only Harbor Lights (2019)
  Fog Country: only Low Tide (2021)

  Not in any collection
  612 of your 1,140 movies (53.7%)

  Playlists with missing items
  Movie Night: 2 of 18 items, such as
    Lanterns S02E03 and Paddock (2016)

  Worth knowing
  These are only the playlists of the
  account Cinemetric signed in with.
Example reply with made-up data. Claude's wording will vary.

watch-mix

Do you watch what you keep?

What's on your server next to what actually gets watched: each genre, decade and resolution's share of your movies and shows, beside its share of plays and watch time.

  • Leads with the biggest differences, such as horror is 18% of your movies but 3% of what's watched.
  • By genre, by decade and by quality (4K, 1080p, 720p, SD), for movies and TV separately.
  • The last 12 months, or any number of months you name.
  • For the whole server it names no one; ask about one person and it covers just them.
  • Facts only: it never tells you to add or remove anything.
  • Watch time comes from Tautulli; with Plex alone it's finished plays times each title's length.

Ask Claude: Do we actually watch the horror movies? or How does what we watch compare with what's on Plex?

Claude Code
> Do we watch what's on Plex?
⏺ Mostly, with a few big gaps. Horror
  is 18% of your movies but 3% of the
  time spent watching them; drama is
  30% of the movies and half of the
  watching. Over the last 12 months.

  Movies, watched more  shelf  watched
  Drama                   30%      50%
  1990s                   14%      27%
  Comedy                  41%      49%

  Movies, watched less
  Horror                  18%       3%
  2020s                   22%      11%
  Documentary              9%       2%

  TV, watched more
  Animation                5%      22%
  Reality                  4%      15%

  Worth knowing
  Watch time is from Tautulli. Genres
  overlap, so they add up past 100%.
  2020s films are newer, so they've
  had less time to be watched.
Example reply with made-up data. Claude's wording will vary.

export

Your whole library in a spreadsheet.

One Excel file with a tab for each part: your server's details, your movies, your TV shows, and the things worth tidying up. It opens in Excel, Numbers, LibreOffice and Google Sheets.

  • Movies and TV shows on their own tabs, with year, date added, length, quality, codecs, size, missing files, watched status and collections.
  • Tabs for issues, episode gaps, files likely to transcode and subtitle problems, straight from those skills.
  • One row per show, or per episode if you ask.
  • Saved privately on your computer, or in a folder you choose. It never replaces a file of yours without asking.
  • No one's names or viewing history are in the file, and nothing in it can run when it's opened.

Ask Claude: Export my Plex library to a spreadsheet or Save a list of every movie I have to my Documents folder

Your spreadsheet
A real Cinemetric export open in a spreadsheet program on its Movies tab: zoomed in on its first columns, one row per movie with library, title, year and date added, with filter buttons on the column names, and tabs along the bottom for Server, Movies, TV Shows, Issues, Episode gaps, Playback and Subtitles.
A real exported workbook, filled with made-up sample titles, open in LibreOffice.

year-in-review

A year of watching, on one page.

Hours watched, the busiest months and the busiest day, movies vs TV vs music, and the most watched movies, shows and artists for any calendar year.

  • The whole-server recap names no one, and leaves off titles only one person watched, so it never gives away what someone else watches.
  • Or make one of your own year, or one person's to give to them.
  • Saved on your computer, as a private claude.ai page, or both. Run it again in December and the same page updates.
  • Hours come from Tautulli; with Plex alone it counts plays.

Ask Claude: Make our Plex year in review or Show me my year on Plex

Your browser
A real Cinemetric year-in-review page in dark mode for 2025: hours watched, plays, titles, days with something on and how many people watched, a bar chart of hours per month with the busiest month marked and the busiest day, the split between movies, TV and music, the most watched movies, shows and music artists with how many people played each, and a note that titles only one person watched were left out. No names appear on it.
A real recap page, filled with made-up sample data. Scroll inside it to see more.

dashboard

The big picture, on one good-looking page.

Library stats, server status (version, updates, remote access and anything that needs a look), the last 30 days of watching, what nobody has finished in a while, gaps in your TV episodes, files likely to transcode, and who your server is shared with, together, with charts. Ask Claude to refresh it whenever you like.

  • Save it on your computer, as a private claude.ai page you can open from anywhere, or both.
  • Each refresh updates the same file and the same link, so your bookmarks keep working.
  • Charts for plays per day, storage added per month, and trends over the saved snapshots: storage, titles per library and people with access.
  • Can hide people's names (viewers and the people you share with), handy before you share it.
  • Nothing runs in the background. It updates only when you ask.

Ask Claude: Build my Plex dashboard

Your browser
The real Cinemetric dashboard in dark mode: library size, plays and watch time, a section listing what changed since Sep 27: titles added and removed, new episodes, files Plex can't find, a Plex update and sharing changes, trend charts of storage, titles in each library and people with access since Jul 8, a server card with an update notice, a plays-per-day bar chart, top shows, movies, music and viewers, the library table with a storage-added-per-month bar chart, titles nobody has finished in six months, gaps in TV episodes, files likely to transcode with the devices and people that transcode most, and who the server is shared with.
The real dashboard, filled with made-up sample data. Scroll inside it to see more.

Extras for Claude Code

Mods, built right in.

Mods are small add-ons that run inside Claude Code (the terminal and the desktop app's Code tab). They come with Cinemetric, so there's nothing extra to install, and each one has its own on/off switch.

Read-only guard

On by default Name: guard

Cinemetric's skills only read from your server. The guard also checks the commands Claude writes on its own: if one would change something on your Plex server, Tautulli or plex.tv (deleting a title, starting a library scan, marking something watched), it stops it before it runs. It also hides your Plex token and Tautulli API key from what Claude sees, and stops Claude putting them in files, issues or pages.

A safety net, not a guarantee. It reads each command before it runs, so it can't see inside a program Claude saves to a file and runs later. It's meant to be turned off only by you.

Library status line

Off by default Name: status

A quiet line just above the prompt showing how big your library is and when Cinemetric last checked it:

Plex: 1,970 movies · 417 shows · 59.4 TB · checked today

It never contacts your server. Instead it reads the snapshot Cinemetric saves each time you ask what changed or refresh the dashboard, so it's only as current as the last time you did one of those.

Now Playing

Off by default Name: now

Type /cinemetric-now to open a panel showing who's streaming right now: what they're watching, on which device, and whether it's playing directly or being transcoded:

3 streams · 1 transcoding · 31.2 Mbps · updated 9:41 PMalex · Arrival (2016) · Roku · playing 42% · direct playsam · Dune (2021) · iPhone · paused 10% · transcode (video)jo · Bluey S02E14 · iPad · playing 77% · direct stream

It checks your server about every 30 seconds, only while the panel is open, and what it shows stays on your screen, never sent to Claude.

Shows who's watching. Since the panel lists people by name, it never opens by itself, only when you ask.

Switching mods on and off

Type this in Claude Code to see every mod and whether it's on:

/cinemetric-mods

Add a mod's name and on or off to switch it. For example, to turn on the status line:

/cinemetric-mods status on

Each mod also has a switch in Claude Code's settings menu, opened with /config.

The guard is the one exception to who can switch things: it's meant to be turned off only by you. Cinemetric refuses Claude's usual ways of turning it off, so Claude can't casually switch off its own safety net.

Mods need Claude Code 2.1.260 or newer, and work best in your terminal: some versions of the desktop app can't show the status line or the Now Playing panel. If /cinemetric-mods says it isn't installed, every skill still works, and the README explains how to switch the mods on.

Built to be trusted

Look, don't touch.

Cinemetric reads from your server and never writes to it, and the read-only guard, an extra safety net, stops Claude's own commands from changing it and keeps your Plex token and Tautulli API key out of Claude's sight. Your keys stay with you.

  • Read-only, always

    Every skill only reads. Nothing on your Plex server or in Tautulli is ever deleted, renamed or changed.

  • Keys stay private

    Your Plex token and Tautulli key go straight into a file only you can read. They never pass through the chat.

  • Encrypted by default

    Certificates are checked unless you say otherwise. It only talks to your server, Tautulli and plex.tv (for sign-in and your share list).

  • Nothing to install

    Small Python scripts using only the standard library. No pip installs, no background services, no SSH.

Getting started

Up and running in four steps.

You'll need Claude Code 2.1.75 or newer (2.1.260 or newer for mods), Python 3.8 or newer, and a computer that can reach your Plex server over the network. Cinemetric works best in Claude Code in your favorite terminal.

Do each of these steps in Claude Code:

  1. Add the marketplace

    /plugin marketplace add jeremehancock/cinemetric
  2. Install the plugin

    /plugin install cinemetric@cinemetric
  3. Connect your server

    Ask Claude Set up Cinemetric (or run the command below). Open the Sign in with Plex link it gives you, approve Cinemetric, tell Claude you're done, then pick your server. Cinemetric tests the connection and saves it.

    /cinemetric:setup
  4. Start asking

    • Give me a Plex library report
    • How's my Plex server doing?
    • What's been watched on Plex this month?
    • Build my Plex dashboard
Add Tautulli (optional)

If you run Tautulli, ask Claude to add Tautulli to Cinemetric and tell it your Tautulli address. You get watch time, devices and busiest times. Your API key never goes through the chat:

  • No login on Tautulli? Cinemetric fetches the key from Tautulli itself.
  • Tautulli has a login? Claude gives you a link to a small one-time page that runs only on your computer. Paste the key from Settings → Web Interface → API and click Test and save.
  • Claude Code on another machine (over SSH or in the cloud)? Claude gives you a command to run in a terminal on that machine instead.

Full Tautulli details in the README

Mods (optional)

Mods come with Cinemetric, so there's nothing more to install. The read-only guard is already on. Everything else, like the library status line, starts off. To see them all and whether each is on:

/cinemetric-mods

Mods need Claude Code 2.1.260 or newer. What each mod does and how to switch them

Set up manually

Create ~/.config/cinemetric/config.json yourself, in your own editor (don't paste your token into a chat):

{
  "plex_url": "http://192.168.1.10:32400",
  "plex_token": "YOUR-TOKEN-HERE"
}

Then make it private to you:

chmod 600 ~/.config/cinemetric/config.json

You can also use PLEX_URL and PLEX_TOKEN environment variables instead.

Manual setup in the README

Revoke access

In Plex, go to Settings → Authorized Devices and remove Cinemetric. Run setup again any time to reconnect. If you used manual setup and think a token leaked, use sign out of all devices in your Plex account settings.

Revoking access in the README

AI can make mistakes

Cinemetric's scripts collect the numbers, but the reports you read are written by Claude, an AI model. It can misread data or draw a conclusion the numbers don't fully support. Double-check anything important in Plex or Tautulli before acting on it, especially before deleting, replacing or re-encoding files.

Changes are up to you

Cinemetric only reads, but Claude can do more than run its skills. If you ask Claude to change something on your server, Claude Code shows you each command first, so give it a read before you approve. For extra peace of mind, switch off Allow media deletion in Plex (Settings, Library), and Plex won't delete media files for any app.

Support development

Cinemetric is free and always will be. If it has earned a spot in your setup, you can throw a few dollars at ongoing development. Or, let's be honest, at another hard drive for the server that is definitely not running out of room.

Buy me a coffee