Jellysweep is a smart cleanup tool for your Jellyfin media server. It automatically removes old, unwatched movies and TV shows by analyzing your viewing history and user requests. With disk usage-aware cleanup thresholds, it can accelerate deletion when storage becomes critical while maintaining reasonable grace periods during normal operation.

• 🧠 Smart Analytics - Checks jellyseerr for requests and Jellystat/Streamystats for stats
• 🏷️ Tag-Based Control - Leverage your existing Sonarr/Radarr tags to control jellysweep
• 💾 Disk Usage Monitoring - Adaptive cleanup based on disk usage thresholds checked during cleanup runs
• 🧹 Flexible Cleanup Modes - Choose between complete deletion, keeping first episodes, or preserving early seasons
• 👥 User Requests - Built-in keep request system for your users
• 🔔 Notifications - Email users, ntfy alerts for admins, and web push notifications
• 📱 Progressive Web App (PWA) - Install as an app on mobile and desktop
• ⚡ Stateless Design - No database required, clean runs every time
• 🌐 Web Interface - Modern UI for monitoring and management
• 📊 Statistics Dashboard - Visual charts showing cleanup progress and storage freed

• Jellysweep
  • ✨ Key Features
  • 📋 Table of Contents
  • 🚀 How It Works
  • 🧹 Cleanup Modes
  • 💾 Disk Usage-Based Cleanup
    • How It Works
    • Configuration Example
    • Behavior Examples
    • Force Deletion Mode
  • 📸 Screenshots
    • Dashboard Overview
    • Statistics Dashboard
    • Admin Panel - Keep Requests
    • Admin Panel - Keep or Sweep
    • Scheduler Panel
  • 🔧 Installation
    • Prerequisites
    • Quick Start
    • Docker Compose
    • Production Docker Compose with Redis Cache
  • 🔐 Authentication
    • OIDC/SSO Authentication
    • Jellyfin Authentication
  • 🔔 Web Push Notifications
    • Setup Requirements
  • ⚙️ Configuration
    • Environment Variables
    • Configuration File
  • 🏷️ Tag System
    • Automatic Tags
    • Custom Tags
  • 🚀 Performance & Caching
    • Cache Types
    • Cache Benefits
    • When to Use Redis Cache
    • Cache Configuration
  • 🔧 Commands
  • 🤝 Contributing
    • Development Setup
  • 📄 License

1. Data Collection

   • Fetches media from Jellyfin
   • Fetches media from Sonarr & Radarr
   • Retrieves viewing statistics from Jellystat or Streamystats
   • Analyzes content history from Sonarr & Radarr
   • Maps media across libraries and services
   • Monitors disk usage for each library during cleanup runs

2. Media Filtering

   • Applies configurable streaming history thresholds
   • Applies configurable age thresholds
   • Applies configurable size thresholds
   • Respects custom exclude tags
   • Respects user keep requests

3. Intelligent Deletion Timing

   • Standard Mode: Uses configured cleanup_delay for deletion timing
   • Disk Pressure Mode: Accelerates deletion based on current disk usage
   • Dynamic Thresholds: Multiple disk usage levels with different cleanup delays
   • Smart Tagging: Creates multiple deletion tags for different scenarios
   • Adaptive Logic: Chooses most restrictive applicable threshold

4. Delayed Deletion

   • Marks media with dated deletion tags
   • Provides grace period for objections
   • Removes recently played content from deletion queue
   • Executes final cleanup after delay
   • Supports force deletion for critical disk space situations

5. User Interaction

   • Users can request to keep specific media
   • Admins can approve/decline requests
   • Automatic cleanup of expired requests
   • Force deletion override for admins
   • Keep requests are blocked for force-delete items

Jellysweep supports three different cleanup modes for TV series, configurable globally through the cleanup_mode setting. The mode determines how much content is removed when a series is marked for deletion. Movies are always deleted entirely regardless of the cleanup mode.

The all mode removes the entire series and all its files, providing maximum storage reclamation. This is the default setting.

The keep_episodes mode preserves the first N episodes across all regular seasons while removing everything else. Episodes are counted by their broadcast order, starting from season 1 episode 1, and special episodes in season 0 are always preserved regardless of the count limit.

The keep_seasons mode retains complete early seasons while removing later ones. It keeps the first N lowest-numbered regular seasons. Specials will not be deleted in this mode either.

Both selective modes automatically unmonitor deleted episodes in Sonarr to prevent them from being redownloaded. If a series has less or equal amount of episode as the keep policy requests, the series wont be marked from deletion again.

Jellysweep monitors disk usage and speeds up cleanup when you're running low on storage. When disk space is tight, it reduces the grace period for deletions while still giving you time to save anything important during normal operation.

• Cleanup-time Monitoring: Checks disk usage for each library path during scheduled cleanup runs
• Multi-tier Thresholds: Configure multiple usage percentage levels with different cleanup delays
• Adaptive Tagging: Creates both standard and disk usage-based deletion tags
• Smart Triggering: Uses the most restrictive applicable threshold based on current usage

libraries:
  "Movies":
    cleanup_delay: 30  # Standard 30-day grace period
    disk_usage_thresholds:
      - usage_percent: 75.0      # When disk usage reaches 75%
        max_cleanup_delay: 14    # Reduce grace period to 14 days
      - usage_percent: 85.0      # When disk usage reaches 85%
        max_cleanup_delay: 7     # Reduce grace period to 7 days
      - usage_percent: 90.0      # When disk usage reaches 90%
        max_cleanup_delay: 3     # Reduce grace period to 3 days

• Normal Operation (80% usage): Media gets jellysweep-delete-2025-08-25 (30-day delay)
• Moderate Pressure (87% usage): Deletion triggered by jellysweep-delete-du85-2025-08-09 (14-day delay)
• High Pressure (93% usage): Deletion triggered by jellysweep-delete-du90-2025-08-02 (7-day delay)
• Critical Pressure (97% usage): Deletion triggered by jellysweep-delete-du95-2025-07-29 (3-day delay)

The jellysweep-must-delete-for-sure tag uses the shortest configured delay across all thresholds:

• Prevents users from submitting keep requests
• Uses the most aggressive cleanup timing available

Main dashboard showing media items scheduled for deletion with filtering and search capabilities

Visual analytics showing daily and cumulative storage cleanup over time

Admin interface for reviewing and approving user keep requests

Admin review interface for making final keep/delete decisions on media items

Control scheduler tasks and view cache statistics

• Access to your Jellyfin ecosystem including:
  • Sonarr
  • Radarr
  • Jellystat or Streamystats
  • Jellyseerr

1. Download & Build

   git clone https://github.com/yourusername/jellysweep.git
   cd jellysweep
   go build -o jellysweep .

2. Configuration

   cp config.example.yml config.yml
   # Edit config.yml with your service URLs and API keys

3. Run

   # Start the service
   ./jellysweep serve
   
   # Reset all tags (cleanup command)
   ./jellysweep reset

For a quick deployment using Docker/Podman, create a compose.yml file:

services:
  jellysweep:
    image: ghcr.io/jon4hz/jellysweep:latest
    container_name: jellysweep
    ports:
      - "3002:3002"
    volumes:
      # - ./config.yml:/app/config.yml:ro use config or env vars
      - ./data:/app/data
      # Mount Jellyfin library paths at the same locations for disk usage monitoring
      # Example: if Jellyfin has /data/movies, mount it the same way here
      # - /data/movies:/data/movies:ro
      # - /data/tv:/data/tv:ro
    environment:
      # Override config values via environment variables if needed
      - JELLYSWEEP_DRY_RUN=false
      - JELLYSWEEP_LISTEN=0.0.0.0:3002
    restart: unless-stopped
    networks:
      jellyfin-network:

networks:
  jellyfin-network:
    external: true  # Assumes you have a shared network with your Jellyfin stack

Then run:

# Start the service
docker compose up -d

# View logs
docker compose logs -f jellysweep

# Reset all tags (cleanup command)
docker compose exec jellysweep ./jellysweep reset

For production deployments with Redis caching, you can use Valkey (Redis-compatible) for better performance and shared cache across multiple instances:

services:
  jellysweep:
    image: ghcr.io/jon4hz/jellysweep:latest
    container_name: jellysweep
    ports:
      - "3002:3002"
    volumes:
      - ./config.yml:/app/config.yml:ro
      - ./data:/app/data
    environment:
      # Cache configuration
      - JELLYSWEEP_CACHE_TYPE=redis
      - JELLYSWEEP_CACHE_REDIS_URL=valkey:6379
      # Other configuration
      - JELLYSWEEP_DRY_RUN=false
      - JELLYSWEEP_LISTEN=0.0.0.0:3002
    restart: unless-stopped
    depends_on:
      - valkey
    networks:
      - jellyfin-network

  valkey:
    image: valkey/valkey:7-alpine
    container_name: jellysweep-valkey
    command: >
      valkey-server
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - valkey_data:/data
    restart: unless-stopped
    networks:
      - jellyfin-network

volumes:
  valkey_data:

networks:
  jellyfin-network:
    external: true  # Assumes you have a shared network with your Jellyfin stack

Benefits of Redis Cache:

• Persistence: Cache survives application restarts
• Performance: Faster data retrieval for frequently accessed items
• Scalability: Shared cache across multiple Jellysweep instances
• Memory Management: Configurable memory limits and eviction policies

Jellysweep supports multiple authentication methods to secure your web interface:

• Tested Providers: Authentik
• Group-based Admin Access: Read admin groups from group claim.
• Single Sign-On: Users authenticate once and access Jellysweep seamlessly

Configuration:

auth:
  oidc:
    enabled: true
    name: Authentik
    issuer: "https://your-sso-provider.com/application/o/jellysweep/"
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    redirect_url: "http://localhost:3002/auth/oidc/callback"
    admin_group: "jellyfin-admins"  # Users in this group get admin access

• Direct Integration: Leverages your existing Jellyfin user database
• Admin Detection: Jellyfin administrators automatically get admin access in Jellysweep
• No Additional Setup: Works out of the box with your Jellyfin instance
• Form-based Login: Traditional username/password login form
• Admin Access: All Jellyfin admins will have access to the admin panel

Configuration:

auth:
  jellyfin:
    enabled: true
    url: "http://localhost:8096"  # Your Jellyfin server URL

Generate VAPID Keys:

# Generate VAPID keys using the built-in command
./jellysweep generate-vapid-keys

Configuration:

webpush:
  enabled: true
  vapid_email: "your-email@example.com"     # Contact email for push service
  public_key: "BMgM07-9XLObs5DGk89rBaT..."  # VAPID public key
  private_key: "dZ-lxXpoCNqyfdfojVt51t..."  # VAPID private key

Jellysweep supports configuration through YAML files and environment variables. Environment variables use the JELLYSWEEP_ prefix and follow the configuration structure with underscores (e.g., JELLYSWEEP_DRY_RUN).

All configuration options can be set via environment variables with the JELLYSWEEP_ prefix:

Jellysweep uses a YAML configuration file with the following structure:

dry_run: false                   # Set to true for testing
listen: "0.0.0.0:3002"           # Web interface address and port
cleanup_schedule: "0 */12 * * *" # Every 12 hours
cleanup_mode: "keep_seasons"     # Cleanup mode: "all", "keep_episodes", or "keep_seasons"
keep_count: 1                    # Number of episodes/seasons to keep (when using keep_episodes or keep_seasons)
session_key: "your-session-key"  # Random string for session encryption
session_max_age: 172800          # Session max age in seconds (48 hours)
server_url: "http://localhost:3002"

# Cache configuration (optional)
cache:
  type: "memory"                 # Cache type: "memory" or "redis"
  redis_url: "localhost:6379"    # Redis server URL (when using redis cache)

# Authentication (optional - if no auth is configured, web interface is accessible without authentication)
# Warning: No authentication is only recommended for development environments
auth:
  # OpenID Connect (OIDC) Authentication
  oidc:
    enabled: false
    name: OIDC
    issuer: "https://login.mydomain.com/application/o/jellysweep/"
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    redirect_url: "http://localhost:3002/auth/oidc/callback"
    admin_group: "jellyfin-admins"     # OIDC group for admin access

  # Jellyfin Authentication
  jellyfin:
    enabled: true                      # Default authentication method

# Jellyfin server configuration
jellyfin:
  url: "http://localhost:8096"         # Your Jellyfin server URL
  api_key: "your-jellyfin-api-key"     # Jellyfin API key

# Profile Pictures (optional)
gravatar:
  enabled: false                       # Enable Gravatar profile pictures
  default_image: "mp"                  # Default image if no Gravatar found
                                       # Options: "404", "mp", "identicon", "monsterid",
                                       #          "wavatar", "retro", "robohash", "blank"
  rating: "g"                          # Maximum rating for images
                                       # Options: "g", "pg", "r", "x"
  size: 80                             # Image size in pixels (1-2048)

# Library-specific settings
libraries:

  "Movies":
    enabled: true
    content_age_threshold: 120
    last_stream_threshold: 90
    content_size_threshold: 1073741824  # 1GB minimum
    cleanup_delay: 60
    exclude_tags:
      - "jellysweep-exclude"
      - "keep"
      - "favorites"
    # Disk usage-based cleanup for movies
    disk_usage_thresholds:
      - usage_percent: 70.0       # When disk usage reaches 70%
        max_cleanup_delay: 30     # Reduce grace period to 30 days
      - usage_percent: 85.0       # When disk usage reaches 85%
        max_cleanup_delay: 14      # Reduce grace period to 14 days
      - usage_percent: 90.0       # When disk usage reaches 90%
        max_cleanup_delay: 7      # Reduce grace period to 7 days
      - usage_percent: 95.0       # When disk usage reaches 95%
        max_cleanup_delay: 2      # Reduce grace period to 2 days

  "TV Shows":
    enabled: true
    content_age_threshold: 120
    last_stream_threshold: 90
    content_size_threshold: 2147483648  # 2GB minimum
    cleanup_delay: 60
    exclude_tags:
      - "jellysweep-exclude"
      - "ongoing"
      - "keep"
    # Disk usage-based cleanup for TV shows
    disk_usage_thresholds:
      - usage_percent: 70.0
        max_cleanup_delay: 30
      - usage_percent: 85.0
        max_cleanup_delay: 14
      - usage_percent: 90.0
        max_cleanup_delay: 7
      - usage_percent: 95.0
        max_cleanup_delay: 2

# Email notifications for users about upcoming deletions
email:
  enabled: false
  smtp_host: "mail.example.com"
  smtp_port: 587
  username: "your-smtp-username"
  password: "your-smtp-password"
  from_email: "jellysweep@example.com"
  from_name: "Jellysweep"
  use_tls: true              # Use STARTTLS
  use_ssl: false             # Use implicit SSL/TLS
  insecure_skip_verify: false

# Ntfy notifications for admins about keep requests and deletions
ntfy:
  enabled: false
  server_url: "https://ntfy.sh"  # Or your own ntfy server
  topic: "jellysweep"
  # Authentication options (choose one):
  username: ""               # Username/password auth
  password: ""
  token: ""                  # Token auth (takes precedence)

# Web push notifications
webpush:
  enabled: false
  vapid_email: "your-email@example.com"  # Contact email for VAPID keys
  public_key: ""                         # VAPID public key (generate with: ./jellysweep generate-vapid-keys)
  private_key: ""                        # VAPID private key

# External service integrations
jellyseerr:
  url: "http://localhost:5055"
  api_key: "your-jellyseerr-api-key"

sonarr:
  url: "http://localhost:8989"
  api_key: "your-sonarr-api-key"

radarr:
  url: "http://localhost:7878"
  api_key: "your-radarr-api-key"

jellystat:
  url: "http://localhost:3001"
  api_key: "your-jellystat-api-key"

# Alternative to Jellystat (configure only one)
streamystats:
  url: "http://localhost:3001"
  server_id: 1                         # Jellyfin server ID in Streamystats

# Cache configuration (optional - improves performance for large libraries)
cache:
  enabled: true                  # Enable caching system
  type: "memory"                 # Options: "memory", "redis"
  redis_url: "localhost:6379"    # Redis server URL (when using redis cache)

Jellysweep uses the tagging feature from sonarr and radarr to track media state:

• jellysweep-delete-YYYY-MM-DD - Media marked for deletion on date (standard cleanup delay)
• jellysweep-delete-du90-YYYY-MM-DD - Media marked for deletion when disk usage ≥90% (example)
• jellysweep-delete-du95-YYYY-MM-DD - Media marked for deletion when disk usage ≥95% (example)
• jellysweep-keep-request-YYYY-MM-DD - User requested to keep (expires)
• jellysweep-must-keep-YYYY-MM-DD - Admin approved keep (expires)
• jellysweep-must-delete-for-sure - Admin forced deletion (prevents keep requests)
• jellysweep-ignore - Media will never be marked for deletion

Configure custom tags in your Sonarr/Radarr to:

• Exclude from deletion: Add tags to exclude_tags list

Jellysweep includes an intelligent caching system to improve performance, especially for large media libraries:

• Memory Cache (default): Fast in-memory caching, data lost on restart
• Redis Cache: Persistent caching with configurable memory limits and eviction policies

• Faster Library Scans: Cached Sonarr/Radarr API responses reduce scan times
• Reduced API Load: Minimizes requests to external services
• Improved Responsiveness: Web interface loads faster with cached data
• Smart Invalidation: Cache is automatically cleared when data changes

Consider Redis cache for:

• Large Libraries: >1000 movies or TV series
• Multiple Instances: Shared cache across Jellysweep instances
• Production Deployments: Persistent cache across restarts
• Resource Optimization: Better memory management and limits

cache:
  enabled: true                  # Enable caching system
  type: "redis"                  # Use Redis for production
  redis_url: "localhost:6379"    # Redis server URL

Cache Options:

• Type: Choose between memory (default) or redis
• Redis URL: Simple address format host:port (no authentication support yet)
• Automatic TTL: Cache expiration is handled by the scheduler, not configurable

Recommended Setup:

• Development: Use memory cache for simplicity
• Production: Use redis cache for persistence and better performance

# Start the main service
./jellysweep

# Start with specific configuration file
./jellysweep --config /path/to/config.yml

# Reset all Jellysweep tags
./jellysweep reset

# Generate VAPID keys for web push notifications
./jellysweep generate-vapid-keys

# Run with custom log level
./jellysweep --log-level debug

# Combine configuration file and log level
./jellysweep --config config.yml --log-level warn

Contributions of all kinds are welcome!

git clone https://github.com/yourusername/jellysweep.git
cd jellysweep
nvm install
npm install --include=dev
go mod download

# Install pre-commit hooks (recommended)
pip install pre-commit
pre-commit install

go run . serve --log-level debug

# build npm dependencies
npm run build

# build templ pages
go tool templ generate

# lint
golangci-lint run

# run tests
go test -v ./...

# run pre-commit checks manually (optional)
pre-commit run --all-files

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality and consistency. The hooks automatically run before each commit and include:

• Code Formatting: Removes trailing whitespace, fixes end-of-file issues
• Validation: Checks YAML/JSON syntax, detects merge conflicts
• Security: Scans for hardcoded secrets and credentials using Gitleaks
• Go Quality: Runs go fmt, go mod tidy, and golangci-lint
• Build Verification: Ensures the project builds successfully with make build

The hooks are configured in .pre-commit-config.yaml and will automatically prevent commits that don't pass all checks.

This project is licensed under the GPLv3 License - see the LICENSE file for details.