docs(skill): make the daemon the default way an agent works

The skill buried daemon mode two-thirds down as a scaling trick, and still
offered --username "$SOULSEEK_USERNAME-$RANDOM" as the way to run commands in
parallel. That is worse than underselling it: the server allows one session
per account, so a per-run name means registering a throwaway account on a
public server for every search — account churn on infrastructure other people
maintain and share.

Starting a daemon is now the first instruction in the file, with the reason
stated, and the random-username idiom is named as the anti-pattern rather than
offered as an alternative. Exit 7's advice changes accordingly: it means
something else logged in as you, and the fix is a daemon, not a new name.

Three agents given only this file and a parallel-work task all started a
daemon and none invented a username.

The startup snippet also had a shell precedence bug: in
`daemon status || daemon &`, the & backgrounds the whole list, so it returned
instantly and the next command raced the login it was meant to use. Replaced
with a bounded wait, checked against a live server.
This commit is contained in:
Michel de Graaf
2026-07-27 14:01:17 +02:00
parent d2599c82d3
commit fe56a070e1
2 changed files with 83 additions and 27 deletions
+20
View File
@@ -129,6 +129,19 @@ soulseek-rs search 'aphex twin' # no login, no flags — uses the daemon
soulseek-rs # the TUI attaches to the same session
```
From a script, start it and wait for it — it takes a second or two to log in,
and a command that arrives early opens a session of its own instead:
```bash
soulseek-rs daemon status --json >/dev/null 2>&1 || {
soulseek-rs daemon >/dev/null 2>&1 &
for _ in $(seq 30); do
soulseek-rs daemon status --json >/dev/null 2>&1 && break
sleep 1
done
}
```
Commands find it by themselves. The daemon listens on a Unix socket only your
user can open, so there is nothing to configure and no secret to pass around —
the same arrangement Docker and ssh-agent use. With no daemon running,
@@ -139,6 +152,13 @@ What this buys: downloads that outlive the command that queued them, several
clients (or agents) on one account at once, and a chat window that keeps
collecting while nothing is attached.
It is also the neighbourly way to use the network. The server allows one
session per account, so parallel one-shot runs either displace each other or
push you into registering a throwaway name per run — account churn on
infrastructure other people maintain. A daemon is one login for as long as you
work, and one share index instead of a rescan per invocation. If you are
driving this from a script or an agent, start a daemon.
```bash
soulseek-rs daemon status # who it is, what it shares, who is attached
soulseek-rs daemon stop