nalbakri/hookreel repository overview

⁠HookReel

AI-powered self-hosted media automation for your home server.

HookReel is a single intelligent agent that manages your entire media library. Ask for movies and TV shows in plain English via Telegram or the built-in web UI — HookReel handles everything from search to download to your media server automatically.

⁠What it does

• Natural language requests — "Find me a good sci-fi movie from the 90s" or "Download Friends Season 2"
• Automatic downloading — searches indexers, picks the best release, downloads via qBittorrent
• Malware scanning — every download scanned with ClamAV before it touches your library
• Media server integration — renames files to Jellyfin- compatible format and triggers library refresh automatically
• Telegram interface — control everything from your phone
• Web UI — dashboard, library browser, chat interface, download manager, and settings — all in one place
• RTMP streaming — stream movies directly to a private Telegram group and watch inline
• TV show support — episode tracking, season management, automatic new episode monitoring
• Library import — import your existing media collection with one command
• Pluggable AI — use DeepSeek, Ollama, or any OpenAI-compatible endpoint
• Pluggable metadata — TMDB, OMDb, or TVmaze

⁠Quick start

⁠Prerequisites

• Docker and Docker Compose
• A Telegram bot token (free, via @BotFather)
• An AI model API key (DeepSeek recommended — free tier available)

⁠Install

Clone the repository and run the setup wizard:

git clone https://github.com/nalbakri/hookreel.git
cd hookreel
python3 setup.py

The wizard walks you through all configuration. When done:

docker compose up -d

That is it. HookReel is running.

⁠First steps after install

1. Open the web UI at http://your-server-ip:8765⁠
2. Send /start to your Telegram bot
3. Ask for a movie: "Find me Interstellar"

⁠What is included in the stack

HookReel connects to your existing qBittorrent and Prowlarr instances, or the setup wizard can configure everything from scratch.

⁠Configuration

All configuration lives in a single config/.env file generated by the setup wizard. Key settings:

AI_MODEL_ENDPOINT   Your AI model endpoint
AI_API_KEY          Your AI API key
METADATA_PROVIDER   tmdb / omdb / tvmaze
TELEGRAM_BOT_TOKEN  Your Telegram bot token
JELLYFIN_ENABLED    true / false

Full configuration reference at: https://github.com/nalbakri/hookreel/blob/master/docs/CONFIGURATION.md⁠

⁠Remote access

HookReel is designed for Tailscale. Install Tailscale on your server and your phone for secure remote access without opening any ports.

⁠Version

Current release: v1.0 Hook

Versions are named after characters from Peter and Wendy.

⁠Links

• GitHub: https://github.com/nalbakri/hookreel⁠
• Documentation: https://github.com/nalbakri/hookreel/blob/master/docs/INSTALL.md⁠
• Issues: https://github.com/nalbakri/hookreel/issues⁠

⁠License

MIT License. See LICENSE for details.