Smart episode management for Sonarr - Get episodes as you watch, clean up automatically when storage gets low.
This project started as scratching my own itch - I wanted more granular series management and couldn't find exactly what I wanted. I'm not a programmer by trade, but I had a clear vision for the solution I needed. I used AI as a development tool to help implement my ideas faster, just like any other tool. The creativity, problem-solving, architecture decisions, and feature design are all mine - AI helped with code, syntax and implementation details. Although I run everything in my own production environment first, it is catered to my environment and is use at your own risk. All code is open source for anyone to review and audit. The tool has been useful for me, and I shared it in case others can benefit from it too - but I absolutely understand if some prefer to stick with established solutions.
- Episeerr
Episeerr automates your TV library with three simple features:
🎯 Episode Selection - Choose exactly which episodes you want
⚡ Smart Rules - For example, next episode ready when you watch, old episodes cleaned up
💾 Smart Cleanup - Automatic cleanup that can be based on when storage gets low
services:
episeerr:
image: vansmak/episeerr:latest
environment:
# Required for all features
- SONARR_URL=http://your-sonarr:8989 # add webhook in sonarr
- SONARR_API_KEY=your_sonarr_api_key
- TMDB_API_KEY=your_tmdb_api_key
# Add your seer info if you want to use episeer to manage by episode
- JELLYSEERR_URL=http://your overseer or jellyseer url #leave field name as jellyseer even if you use overseerr
- JELLYSEERR_API_KEY:
# Add these ONLY if you want viewing automation #add webhook in tautulli
- TAUTULLI_URL=http://your-tautulli:8181
- TAUTULLI_API_KEY=your_tautulli_key
# Or
- JELLYFIN_URL=http://your-JF_URL # ADD WEBHOOK IN JELLYFIN
- JELLYFIN_API_KEY=your_jf_key
- JELLYFIN_USER_ID=
# Optional quicklinks
- CUSTOMAPP_URL=http://192.168.254.205:8080 # example SABNZBD_URL=http...
- CUSTOMAPP_NAME=My Custom App # Optional
- CUSTOMAPP_ICON=fas fa-cog # Optional
volumes:
- ./config:/app/config
- ./logs:/app/logs
- ./data:/app/data
- ./temp:/app/temp
ports:
- "5002:5002"
restart: unless-stopped- Start container and go to
http://your-server:5002 - That's it! You can now use episode selection
- Storage cleanup: Set threshold in Scheduler page
- Smart rules: Create rules for automatic management
- Viewing automation: Add webhooks for next episode ready
- Add
watchedtag in Sonarr: Removes these series from Episeer Series Management
Create rules with the new dropdown system:
Get Episodes:
- Type: Episodes/Seasons/All + Count
- Example: "3 episodes" = next 3 episodes ready
Keep Episodes:
- Type: Episodes/Seasons/All + Count
- Example: "1 season" = keep current season after watching
Create rules with two independent grace timers:
Grace Watched (Rotating Collection):
- Your kept episodes expire after X days of inactivity
- Example: 14 days = watched rotate out after 2 weeks
Grace Unwatched (Watch Deadlines):
- New episodes get X days to be watched if no activity
- Example: 10 days = pressure to watch new content
Dormant Timer (NEW!):
- Removes content from abandoned shows
- Example: 30 days = if no activity for a month, clean up the show
Get: 5 episodes (next 5 episodes ready)
Keep: 2 episodes (last 2 watched episodes)
Grace: 7 days (keep last 2 watched episodes, delete after a week)
Dormant: 60 days (cleanup if abandoned for 2 months)
What happens:
- Watch E10 → Get E11-E15, Keep E9-E10
- After 7 days → Delete E9-10 (grace expired)
- After 60 days no activity → Delete show (series abandoned)
- Set one global threshold: "Keep 20GB free"
- Cleanup only runs when below threshold
- Stops immediately when back above threshold
- Only affects shows with grace/dormant timers
Good for picking specific episodes. Even across seasons.
- Setup: Just the 3 required environment variables
- create sonarr and optional seer webhooks
- No rules needed, no webhooks required
- Use: Manual episode selection interface only
Next episode ready as you watch (optional upgrade).
- Setup: Add Tautulli/Jellyfin webhook + create rules
- No storage management required
- Use: Episodes managed automatically as you watch, get this many, keep this many
Automatic cleanup when storage gets low (optional upgrade).
- Setup: Set storage threshold + add grace/dormant timers to rules
- No viewing automation required
- Use: Hands-off storage management
✅ Intuitive: New dropdown system makes rules easy to understand
✅ Smart: Grace periods that actually make sense
✅ Safe: Storage gate prevents unnecessary cleanup
✅ Flexible: Use only the features you need
✅ Storage-Aware: Cleanup respects your storage limits
Screenshot 
📚 Full Documentation - Complete guides and setup
Quick Links:
- Installation Guide - Docker setup and configuration
- Rules Guide - Creating and managing rules
- Episode Selection - Manual episode management
- Storage Gate - Automatic cleanup system
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Coffee: Buy Me A Coffee ☕
Simple, smart episode management that just works.