## π SuggestArr - Media Automation Made Simple
[](https://buymeacoffee.com/suggestarr)
[](https://discord.com/invite/JXwFd3PnXY)
SuggestArr is a project designed to automate media content recommendations and download requests based on user activity in media servers like **Jellyfin**, **Plex**, and now **Emby**. It retrieves recently watched content, searches for similar titles using the TMDb API, and sends automated download requests to **Seer**.
New jobs follow the global **Approve requests before sending them to Seer** setting,
disabled by default under **Advanced**. Each job can inherit that setting or override
it to always approve or always send automatically. Held results appear on the
Requests page, where the job owner or an administrator can send them to Seer,
reject them, or blacklist them globally.
The global Request Workflow settings can also pause a job while its SuggestArr
suggestions await review and automatically reject suggestions left pending for a
configured number of days. The pause behavior can be overridden per job.
## Features
- **Multi-Media Server Support**: Supports Jellyfin, Plex, and Emby for retrieving media content.
- **TMDb Integration**: Searches for similar movies and TV shows on TMDb.
- **AI-Powered Recommendations** *(beta)*: Uses any OpenAI-compatible LLM (OpenAI, Ollama, Gemini, LiteLLMβ¦) to generate hyper-personalized suggestions based on watch history, complete with AI reasoning for each pick.
- **AI Search** *(beta)*: Describe in natural language what you want to watch and let the AI find matching titles, personalised to your viewing history, with one-click request to Seer.
- **Trakt Watch History**: Let each user link their own Trakt account. SuggestArr can use Trakt recent watches as recommendation seeds and skip content already watched on Trakt.
- **Automated Requests**: Sends download requests for recommended content to Seer.
- **Pending-Request Job Pause**: Skip scheduled or manual jobs while Seer still has requests waiting for approval or denial.
- **Unwatched-Suggestion Pause**: Optionally pause scheduled recommendation jobs when a user has not watched a SuggestArr request within a configurable number of days; manual runs remain available.
- **Cleanup Automation**: Optionally prune old SuggestArr-originated requests and files when users never favorite them in Plex, Jellyfin, or Emby.
- **Web Interface**: A user-friendly interface for configuration and management.
- **Real-Time Logs**: View and filter logs in real time (e.g., `INFO`, `ERROR`, `DEBUG`).
- **User Selection**: Choose specific users to initiate requests, allowing management and approval of auto-requested content.
- **Per-User Request Visibility**: Filter requests by media-server account, or let administrators limit regular users to requests for their linked Plex, Jellyfin, or Emby account.
- **Cron Job Management**: Update the cron job schedule directly from the web interface.
- **Configuration Pre-testing**: Automatically validates API keys and URLs during setup.
- **Content Filtering**: Exclude requests for content already available on streaming platforms in your country.
- **External Database Support**: Use external databases (PostgreSQL, MySQL) in addition to SQLite for improved scalability and performance.
## Prerequisites
- **Python 3.x** or **Docker**
- **[TMDb API Key](https://www.themoviedb.org/documentation/api)**
- Configured **[Jellyfin](https://jellyfin.org/)**, **[Plex](https://www.plex.tv/)**, or **[Emby](https://emby.media/)**
- Configured **[Seer](https://github.com/seerr-team/seerr)**
- (Optional) External database (PostgreSQL or MySQL) for improved performance
- (Optional) **[Trakt OAuth application](https://trakt.tv/oauth/applications)** for per-user Trakt watch-history integration
## Docker Usage
You can run the project using Docker Compose for easy setup and execution.
### Docker Compose Example
```yaml
services:
suggestarr:
image: ciuse99/suggestarr:latest
container_name: SuggestArr
restart: always
ports:
- "${SUGGESTARR_PORT:-5000}:${SUGGESTARR_PORT:-5000}"
volumes:
- ./config_files:/app/config/config_files
environment:
# Optional: Only needed if something goes wrong and you need to inspect deeper
- LOG_LEVEL=${LOG_LEVEL:-info}
# Optional: Customize the port (defaults to 5000 if not set)
- SUGGESTARR_PORT=${SUGGESTARR_PORT:-5000}
```
To start the container with Docker Compose:
```bash
docker-compose up
```
## Web Interface
Access the web interface at: http://localhost:5000 (or your custom port if configured with SUGGESTARR_PORT). Use this interface to configure the application, select your media service, and manage cron schedules.
Make sure your environment is set up correctly and that the application is running to access the web interface.
### Using a Specific Seer User for Requests
If you'd like to use a specific Seer user to make media requests, follow these steps:
1. In the web interface, enable the user selection option by checking the corresponding box.
2. Select the desired user from the dropdown list.
3. Enter the password for the selected user.
4. The system will now use this user to make media requests, rather than using the admin or default profile.
Note: Currently, only local Seer users are supported.
## Trakt Watch History Integration
SuggestArr can enrich recommendations with each user's own Trakt watch history. Trakt is optional: media-server history still works without it.
### What Trakt adds
- Recent Trakt watches can be used as recommendation seeds.
- Fully watched Trakt items can be added to the skip-watched set.
- Each SuggestArr user links their own Trakt account from their profile.
- Admins configure only the shared Trakt app credentials.
- A collapsible **Recent Trakt Preview** panel shows the latest items fetched from Trakt when opened.
### How to enable
1. Create a Trakt OAuth app at .
2. In SuggestArr, go to **Services -> Trakt**.
3. Enter the Trakt **Client ID** and **Client Secret**, then save.
4. Each user goes to **Profile -> Trakt Account** and clicks **Link Trakt**.
5. Enter the Trakt device code shown by SuggestArr at the Trakt activation URL.
6. Open **Recent Trakt Preview** to verify the latest Trakt history is being read.
For admins, the same profile panel is available under **Users**. Trakt links are tied to the user's linked Plex, Jellyfin, or Emby media profile, so users should link their media-server account first.
## Job Pause and Cleanup Automation
SuggestArr includes two safety tools for running automation without flooding Seer or keeping unwanted media forever.
### Pause jobs while Seer has pending requests
Each job has a **Pause while Seer requests are pending** option in its schedule settings.
When enabled, SuggestArr checks Seer before running that job. If Seer has requests still awaiting approval or denial, the job is skipped and logged as paused/skipped. This applies to scheduled runs, single job runs, and force-run-all.
Recommendation and Trakt Recommendation jobs can also enable **Pause if suggestions remain unwatched**. Movie and TV activity is tracked separately per linked media user. Watching a requested movie or one episode of a requested show starts a fresh cycle; only scheduled runs are paused.
Use this when Seer approvals are part of your workflow and you want new automation runs to wait until the previous batch has been reviewed.
### Cleanup Automation
Cleanup Automation is available under **Advanced -> Cleanup Automation**.
It looks at requests created by SuggestArr, waits for the configured grace period, checks whether the item is favorited in Plex, Jellyfin, or Emby, and then:
- keeps favorited items
- skips items no longer present in the media library
- logs what would be deleted in dry-run mode
- asks Seer to delete matching media files when real mode is enabled
Cleanup is off by default and starts safely in dry-run mode. Always run dry-run first and review the audit log before enabling real deletions.
## AI-Powered Recommendations (Beta)
SuggestArr includes an optional AI recommendation engine that analyzes your watch history and suggests titles that match your taste, with a short explanation for each pick.
The engine works with **any OpenAI-compatible API**, so you can use a cloud provider or a local model running on your own machine.
### How to enable
1. Open the web interface and go to **Settings β Advanced**.
2. Check **Enable beta features**.
3. Check **Use advanced suggestion algorithm**.
4. Fill in the **AI Provider Configuration** fields that appear (click the **β** button next to the section title for an in-app guide).
5. Save. The AI engine will be used automatically on the next automation run.
> If the LLM is unavailable or returns no results, SuggestArr falls back to the standard TMDb-based recommendation algorithm transparently.
### Supported providers
| Provider | API Key | Base URL | Example model |
|---|---|---|---|
| **OpenAI** | Required (`sk-proj-...`) | *(leave blank)* | `gpt-4o-mini` |
| **Ollama** (local) | Not required | `http://localhost:11434/v1` | `mistral`, `llama3` |
| **OpenRouter** | Required (`sk-or-v1-...`) | `https://openrouter.ai/api/v1` | `meta-llama/llama-3-8b-instruct` |
| **LiteLLM Proxy** | Depends on config | `http://:4000` | Depends on config |
**Note for Ollama users:** make sure Ollama is running and the model is pulled (`ollama pull mistral`) before saving. The API Key field can be left blank β SuggestArr will use a placeholder automatically.
### Docker Compose with Ollama (example)
```yaml
services:
suggestarr:
image: ciuse99/suggestarr:latest
container_name: SuggestArr
restart: always
ports:
- "5000:5000"
volumes:
- ./config_files:/app/config/config_files
ollama:
image: ollama/ollama
container_name: ollama
restart: always
ports:
- "11434:11434"
volumes:
- ollama_data:/root/.ollama
volumes:
ollama_data:
```
After starting both containers, pull your preferred model:
```bash
docker exec -it ollama ollama pull mistral
```
Then in SuggestArr Advanced settings set:
- **Base URL** β `http://ollama:11434/v1`
- **Model** β `mistral`
- **API Key** β *(leave blank)*
---
## π AI Search (Beta)
SuggestArr includes an **AI Search** tab in the dashboard that lets you find movies and TV shows using plain text, no browsing required.
### How it works
Type a natural-language description of what you feel like watching. The LLM interprets your query (genres, era, language, rating threshold, moodβ¦) and translates it into structured TMDB filters. Results are ranked and enriched with an AI-generated rationale explaining why each title was picked for you.
**Examples of queries you can use:**
- *"A psychological thriller from the 90s with a twist ending"*
- *"Feel-good anime with strong friendships"*
- *"80s sci-fi movies with practical effects"*
- *"A dark comedy series like Breaking Bad"*
### Key capabilities
- **Natural language queries** β describe mood, genre, decade, language, or specific themes
- **Viewing-history personalisation** β the AI tailors results based on what you (or your users) have already watched
- **Exclude already-watched titles** β hide content you've already seen
- **One-click requesting** β send results directly to Seer without leaving the page
- **Query interpretation badge** β see how the AI parsed your query (genres, year range, language, min rating)
### How to enable
AI Search requires an LLM to be configured (same setup as AI-Powered Recommendations):
1. Open the web interface β **Settings β Advanced**.
2. Check **Enable beta features**.
3. Fill in the **AI Provider Configuration** fields (API key, base URL, model).
4. Save. The **AI Search** tab will become active in the dashboard.
> AI Search is independent of the automated recommendations run β it is triggered manually from the dashboard and does not affect cron-based automation.
---
## Installation
For Docker, Unraid, source install, reverse proxy, backup, and recommended configuration instructions, see the [Installation Guide](/docs/INSTALLATION.md).
## Support SuggestArr β€οΈ
If you enjoy SuggestArr, consider making a donation to support its continued development and help keep the project running at its best:
- β [Ko-fi](https://ko-fi.com/ciuse99)
- π [Buy Me a Coffee](https://buymeacoffee.com/suggestarr)
Every contribution, no matter the size, is greatly appreciated. Thank you for supporting SuggestArr!
## Join Our Discord Community
Feel free to join our Discord community to share ideas, ask questions, or get help with SuggestArr: [Join here](https://discord.gg/JXwFd3PnXY).
## Contribute
Contributions are highly welcome! Feel free to open issues, submit pull requests, or provide any feedback that can improve the project. Whether you're fixing bugs, improving documentation, or adding new features, all contributions are greatly appreciated.
## License
This project is licensed under the MIT License.