didactyl/swarm/README.md

Swarm

A swarm is a queen agent plus worker agents that coordinate over Nostr to solve a problem the admin posts.

• queen/ — the queen. Watches the admin's kind 1 posts; when addressed with the phrase "my queen" (case-insensitive) she seeds a swarm.
• worker1/, worker2/ — workers that pick up subtasks.
• admin_post.sh — publish a kind 1 note as the admin (signed by the n_signer).

Each agent runs from its own directory with its own genesis.jsonc and API port:

Agent	Port	Config
queen	8484	queen/genesis.jsonc
worker1	8485	worker1/genesis.jsonc
worker2	8486	worker2/genesis.jsonc

Genesis is consumed once. After first run, all agent state (skills, profile, relay list) lives on the relay. To change an agent, edit the events on the relay — not genesis.jsonc.

Running the queen

The launcher runs the binary in the foreground, so output streams to your terminal:

./swarm/queen/run.sh

Verify it is up:

curl -s http://127.0.0.1:8484/api/status

Following the swarm

nak cannot OR two filters in a single REQ (and -a + -p in one filter is AND, which returns nothing useful), so run two parallel nak streams in one line. -a shows the admin's own posts; -p shows every event that tags the admin (queen/worker replies).

nak req --stream -k 1 -a 8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e ws://127.0.0.1:7777 & nak req --stream -k 1 -p 8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e ws://127.0.0.1:7777 & wait

With labels and readable formatting (requires jq):

nak req --stream -k 1 -a 8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e ws://127.0.0.1:7777 | jq -r '"ORIG  \(.created_at)  \(.content[0:80]|gsub("\n";" "))"' & nak req --stream -k 1 -p 8ff74724ed641b3c28e5a86d7c5cbc49c37638ace8c6c38935860e7a5eedde0e ws://127.0.0.1:7777 | jq -r '"REPLY \(.created_at)  \(.content[0:80]|gsub("\n";" "))"' & wait

Notes:

• --stream replays existing history first, then stays live. To start from now only, add -s $(date +%s) to each.
• The admin hex 8ff74724… is the decoded form of npub13lm5wf8dvsdnc2894pkhch9uf8phvw9varrv8zf4sc885hhdmc8q6lx7ks. nak accepts the npub too, but hex is unambiguous.
• This shows the queen's root and claim events (both tag the admin with p), so you see the full swarm activity.

Why the web feed misses replies

feed.html (in client_local) is a feed, not a thread viewer. It fetches exactly one level of replies to each top-level post (#e: [postIds]), so nested replies — e.g. the queen's claim, which replies to her own root rather than to the admin's post — are never fetched. Use the nak streams above to follow the full thread.

Managing the relay list

The relay list is stored on Nostr as replaceable events signed by the agent's key: kind 10002 (NIP-65 relay list) and kind 10050 (DM relays). To change it, publish new events — editing genesis.jsonc only matters on re-bootstrap.

Add a relay to the queen (replace <QUEEN_NSEC> and the relay URL):

nak event --sec <QUEEN_NSEC> -k 10002 -t r=ws://127.0.0.1:7777 -t r=wss://example.net/relay ws://127.0.0.1:7777
nak event --sec <QUEEN_NSEC> -k 10050 -t relay=ws://127.0.0.1:7777 -t relay=wss://example.net/relay ws://127.0.0.1:7777

Read the current list back:

nak req -k 10002 -a <QUEEN_HEX> ws://127.0.0.1:7777
nak req -k 10050 -a <QUEEN_HEX> ws://127.0.0.1:7777