Michel de Graaf
6927e91274
Feedback from a real 32-track run: 70 agents, 2.48M tokens, 18.7 minutes, most of it avoidable. Four things, three adopted as reported and one corrected. The skill mandated a handoff it gave no mechanism for. Subagents had to report a pick, while the rules said remote paths are backslash-separated, may contain anything, and must be passed back byte-identical. A path does not survive a subagent's return, a coordinator's JSON and a child's argv, so every agent re-derived a workaround from prose. The idiom is now written down: append every rung to one ndjson file, select the pick by line number, feed it to `download --stdin`. The bytes never leave the file, and a subagent reports a file and a line rather than a path. `get` is now the default and subagents the exception. It searches, ranks and downloads in one command, so results never enter any context, which is where the tokens went. The section says when to escalate: a named mix, an ambiguous title, four dead rungs, or several runs landing on the same peer. Browsing triggers on any artist appearing more than once, not only on a whole album. In the reported set that was 14 of 32 tracks across six artists. The one correction: "rung 2 empty means rungs 3 and 4 are ceremony" is not safe, because rung 3 folds diacritics and punctuation and that is often exactly why rung 2 found nothing. The general rules are that a rung producing the same string as the last is not a rung, and that no results at all means the tokens are wrong rather than too many, so jump to the widest rung instead of stepping. Streaming picks into transfers is untouched; the report singled it out as working. Checked against agents given only this file on the same shape of set: both lead with `get`, spawn 3 and 6 subagents rather than 32, keep result sets out of context, browse the repeated artists, and hand paths over as a file and a line number.
soulseek-rs
A Soulseek client for the terminal: a full-screen TUI, and a one-shot command surface built for scripts and agents.
Website: https://re-invention.nl/soulseek-rs/
Installation
brew install michel/tap/soulseek-rs # macOS and Linux, prebuilt
cargo install soulseek-rs # anywhere with a Rust toolchain
Usage
Run it with no subcommand for the interactive TUI:
soulseek-rs
Anything else is a one-shot command that runs headless. stdout carries records only, stderr carries progress, and the exit code carries the verdict:
soulseek-rs search <QUERY> # print matching files
soulseek-rs get <QUERY> # search, pick the best, download
soulseek-rs download <USER> <PATH> # fetch one known file
soulseek-rs download --stdin # fetch files listed on stdin
soulseek-rs browse <USER> # list a user's shared files
soulseek-rs serve [--follow] # stay online sharing, stream uploads
soulseek-rs whoami # confirm credentials and connection
soulseek-rs user <NAME> # a peer's status and share counts
soulseek-rs room list|say|users|listen
soulseek-rs message send|read
soulseek-rs shares list|add|remove|status|reindex
soulseek-rs config path|list|get|set
soulseek-rs portmap # test automatic port mapping
soulseek-rs completions install # tab completion for bash/zsh/fish
Add --json for newline-delimited JSON instead of tab-separated text, so
commands compose:
soulseek-rs search "rjd2" --json \
| jq -c 'select(.size > 5000000 and .free_slot)' \
| soulseek-rs download --stdin
Exit codes: 0 success, 2 usage or config, 3 connect or login, 4 nothing
found, 5 timed out, 6 transfer failed, 7 session lost mid-command, 1
unexpected error.
The full README documents every
command, record shape, flag, environment variable and config.toml key.
Building from Source
git clone https://github.com/michel/soulseek-rs.git
cd soulseek-rs
cargo build --release
Library
To build your own Soulseek client, use the soulseek-rs-lib crate: the protocol implementation this client is built on.