swarmselect

swarmselect is a terminal-first torrent search and ranking tool.

It searches Prowlarr, cleans up noisy tracker results, applies deterministic filters, uses an LLM to rank candidates, and can pass the chosen result to aria2c for download.

The point is not to be a full torrent client. The point is to make "which release should I trust?" much faster and much clearer.

Legal / Safety

This project is not intended for illegal use, copyright infringement, or downloading content you do not have the right to access.

It is meant for lawful torrent workflows such as open-source software distribution, public-domain media, licensed archives, and other content you are legally permitted to download and share.

You are responsible for complying with the laws, tracker rules, and content licenses that apply in your jurisdiction.

What It Does

• searches Prowlarr
• removes obvious junk before LLM ranking
• parses query intent like movie vs TV and season/episode structure
• uses query rewrites and fuzzy relevance to choose better candidates
• supports deterministic filters like size and seeder bounds
• supports batch files and an opt-in smart batch mode
• can download through aria2c
• launches a TUI for interactive review

Current Shape

This is a serious prototype, not a finished app.

What already works:

• first-run bootstrap when config or aria2c is missing
• Bubble Tea TUI launched by swarmselect or swarmselect menu
• setup
• search
• batch
• smart-batch behind an opt-in flag
• local config file with migration from the old app name
• local aria2c bootstrap on Windows

What is still evolving:

• ranking quality
• TV-specific matching
• smart batch planning quality
• downloader ergonomics
• deeper TUI polish

Architecture

swarmselect currently works in this order:

1. Parse query intent with the LLM
2. Generate query variants
3. Search Prowlarr
4. Drop zero-seeder and obviously bad candidates
5. Rank top candidates by fuzzy relevance
6. Apply deterministic filters and heuristics
7. Ask the LLM to review survivors
8. Pick the best result or refuse auto-pick when confidence is too low
9. Ask whether to download

First Run

Fastest path:

swarmselect

On first run, swarmselect will:

• check whether config already exists
• install a local copy of aria2c if needed
• help you point the app at Prowlarr
• prompt once for API keys and defaults

You can still run setup directly:

swarmselect setup

Config is saved to:

C:\Users\<you>\AppData\Roaming\swarmselect\config.json

If you previously used the old app name, swarmselect will migrate config from:

C:\Users\<you>\AppData\Roaming\torrent-picker\config.json

Example Config

{
  "prowlarr_url": "http://localhost:9696",
  "prowlarr_api_key": "your-prowlarr-api-key",
  "openrouter_api_key": "your-openrouter-api-key",
  "openrouter_model": "arcee-ai/trinity-large-preview:free",
  "min_confidence": 0.75,
  "smart_batch_enabled": false
}

Environment overrides still work:

$env:PROWLARR_URL="http://localhost:9696"
$env:PROWLARR_API_KEY="your-prowlarr-api-key"
$env:OPENROUTER_API_KEY="your-openrouter-api-key"
$env:OPENROUTER_MODEL="arcee-ai/trinity-large-preview:free"
$env:TORRENT_PICKER_MIN_CONFIDENCE="0.75"

Commands

Launch the interactive app:

swarmselect
swarmselect menu

Run one search:

swarmselect search "ubuntu 24.04 desktop"
swarmselect search "debian netinst amd64" --size-lt 5GB
swarmselect search "blender demo files" --seeders-gte 3
swarmselect search "public domain film archive" --include 1080p --exclude cam,ts

Useful output modes:

swarmselect search "ubuntu 24.04 desktop" --dry-run
swarmselect search "ubuntu 24.04 desktop" --json

Read newline-delimited queries from a file:

swarmselect batch queries.txt

Example queries.txt:

ubuntu 24.04 desktop
debian netinst amd64
blender demo files

Use opt-in smart batch mode:

swarmselect smart-batch "download me three Linux distributions"

Filter Flags

Deterministic filters run before final LLM ranking.

• --size-lt 5GB
• --size-gt 2GB
• --seeders-gte 3
• --seeders-lte 50
• --resolution 1080p,2160p
• --source webdl,bluray
• --codec h264,h265
• --include remux
• --exclude cam,ts,open matte

Examples:

swarmselect search "ubuntu desktop" --size-lt 6GB
swarmselect search "public domain film archive" --include 1080p --exclude cam
swarmselect search "debian netinst amd64" --seeders-gte 5

TUI

The current TUI is review-first:

• home screen
• search input
• batch file input
• smart batch plan view
• result review screen
• download confirmation modal

See TUI_PLAN.md for the implementation plan and future polish direction.