pt-tools
RSS → downloader · cross-site stats · web + ChatOps · one Go binary
Hand over the repetition, keep the judgement. Running accounts on several private trackers is a fixed set of motions: check the feeds, see what is free, hand it to a downloader, come back later to clean up, and total the numbers at the end of the month. None of it is difficult; all of it needs someone watching. pt-tools takes those loops over, and every loop carries its own bound — H&R protection, a minimum free-disk floor, and an explicit policy for what happens when a free window closes.
With no filter rule enabled, RSS downloads free torrents only
This is the default on the subscription path, and the single easiest thing to misread. With no filter rule enabled, RSS downloads free torrents only — it does not pull the whole feed. Getting non-free content into the queue means writing a filter rule yourself. Three kinds are available:
- Keyword — the direct form, matching a string in the title.
- Wildcard — for the cases that already have a naming structure: episodes, seasons, resolutions.
- Regex — for conditions the first two cannot express, at the cost of owning its correctness yourself.
The problem it solves
The difficulty is not in any single action, it is that the actions repeat across several sites indefinitely. Done by hand, the failures are always the same few: a free window closed and the torrent kept downloading; the cleanup rule never actually fired and the disk filled up; a torrent still short of its H&R time got deleted while tidying; and month-end totals meant logging into each site to copy figures out. pt-tools turns those into configuration, executes the configuration, and leaves a record when something goes wrong.
People with accounts on several sites
The cost of checking feeds and copying statistics by hand rises linearly with the number of sites. The aggregate view and one shared subscription config exist for exactly that.
People whose downloader lives on a server
A web UI plus ChatOps means pausing one torrent does not require opening an SSH session. A direct-message window is the console.
People short on disk
Automatic cleanup carries a minimum free-disk floor, and the cleanup rules run alongside H&R protection — space is never reclaimed by deleting a torrent that has not finished seeding.
People whose sessions keep expiring
Login sessions are kept alive: activity is probed on a schedule, a warning arrives while there are still days left, and a refresh is one click from the web UI or the browser extension — rather than a feed that silently stopped matching anything.
Five automation loops
Each loop has a trigger, an action and a bound. The bound column is not supporting detail — it is the reason these loops can be left running.
RSS feed → downloader
Feeds are parsed on a schedule, free torrents identified, and handed to the configured downloader. The .torrent file can also just be saved locally so you decide when to add it.
Free torrents only while no filter rule is enabled. Reaching non-free content requires a keyword, wildcard or regex rule you write yourself.
Cross-site search → batch push
One query reaches several sites; results can be batch-downloaded, batch-pushed to a chosen downloader instance, or saved as local files in bulk.
The push target is an explicitly chosen downloader instance, each with its own save directory and post-add start policy — nothing lands in a shared directory by accident.
Free window closes → pause
The end of a free window is tracked, and the torrents concerned are paused when it arrives, so no download volume accrues afterwards.
Whether incomplete torrents are also deleted at that point is an explicit switch, off by default.
Seeding target met → cleanup
Finished torrents are removed by seed time, ratio or inactivity, returning the space to the next batch.
H&R protection takes precedence over the cleanup rules, and a minimum free-disk floor applies — nothing is deleted for tidiness while there is still room.
Session probe → early warning
Site-side activity is probed periodically, a warning arrives as the remaining days run down, and the session is refreshed from the web UI or the browser extension.
The refresh is a confirmed manual action — expired credentials are not retried in a loop until the account trips a rate limit.
Statistics and the data card
Figures scattered across sites collected into one place, and exportable as a single image.
What is collected
Upload, download, ratio, bonus points and level progress — per site, and as a total.
Data card
The statistics render to a card image for sharing or archiving. It is generated locally; no third-party rendering service is involved.
Version check
Checks whether a newer release exists. A binary deployment can upgrade itself in one step; a container deployment follows its image tag.
ChatOps · since v0.31
The console moves into a chat window, so a torrent can be paused from a phone. Two channels are verified end to end; two others merely send. They are labelled separately below — the difference matters when you actually depend on it.
QQ · OneBot
NapCat reverse WebSocket · DM commands
Connects through NapCat over a reverse WebSocket, with commands issued in a direct message. This channel has been verified in both directions.
Telegram · Bot API
BotFather long-poll · DM commands · proxy support
A bot registered through BotFather, receiving by long poll, with commands issued in a direct message and proxy support available. Also verified in both directions.
WeCom group bot
Group-bot webhook
The code is there, but it has not been verified end to end. Treat it as experimental and do not hang your only alerting path on it.
Custom webhook
HMAC-SHA256 signed
Delivers to a receiver you run, with an HMAC-SHA256 signature on the request. Likewise not verified end to end.
13 built-in commands
- /help
- List commands
- /status
- Runtime status
- /version
- Current version
- /tasks
- Task list
- /sites
- Site list
- /torrents
- Torrent list
- /pause
- Pause
- /resume
- Resume
- /delete
- Delete
- /bind
- Bind an account
- /unbind
- Unbind
- /addrss
- Add a feed
- /delrss
- Remove a feed
Access and credentials
- Only accounts on the list can issue commands; everything else is ignored.
- Five options: 5 minutes, 1 hour, 1 day, 30 days, permanent. The short end is the default.
- Credentials are written AES-GCM encrypted, never in plaintext.
- Outbound webhooks carry an HMAC signature so the receiver can verify the origin.
- Commands and their outcomes are recorded, so who did what and when can be read back afterwards.
Deployment
Two shapes: a container, or a single binary. The binary has no runtime dependency — it is a Go build, so putting it on your PATH is enough.
# pull the image
$ docker pull sunerpy/pt-tools# mount config and data
$ docker run -d -v ./config:/app/config -p 8080:8080 sunerpy/pt-tools# take the archive for your platform off the releases page, extract, put it on PATH
$ pt-tools --help# check the current version and whether an update exists
$ pt-tools versionProxies use the standard environment variables: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, with exceptions in NO_PROXY. A binary deployment can self-upgrade in one step; a container deployment follows its image tag. Ports and data paths are whatever your deployment says — the commands above show the shape, not the only spelling.
Stack
Every choice serves the same goal: one process, one config file, installed on your own machine.
- Go 1.25+. Shipped as a single executable with no runtime dependency.
- A web management UI, plus QQ and Telegram ChatOps channels.
- Multiple instances, each with its own save directory and post-add start policy.
- Honours HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY.
- The sunerpy/pt-tools Docker image, plus binaries for Linux and Windows.
- MIT.
What it does not do
Stating the boundary up front beats explaining it afterwards.
It does not judge the rules for you
Every site has its own rules, its own H&R requirements and its own free policy. The tool executes the configuration you wrote; it does not decide whether an action is appropriate on a given site. A wrong config lands on your account, not on the tool.
It is not a downloader
It orchestrates a downloader rather than implementing one. The actual downloading and seeding is your own client’s job.
It is not an indexer
Search goes through each site’s own interface, so what you can find depends on the access you already have there. It keeps no torrent database of its own.
Two notification channels are unverified
The WeCom group bot and the custom webhook are experimental and have not been verified end to end. Use QQ or Telegram where alerting has to be reliable.
The cost is your own machine
There is no hosted version and no account system. It runs on your host and the site credentials live there too — which is the design stance, and also means backups and security are yours.
Pull an image, or take a binary
The Docker image and per-platform binaries are both below. It is an MIT-licensed personal project; issues and pull requests live in the same repository.