twin
atproto, agents, terminal multiplexers
Star
Fork
Watch
8 1 0
Files
internal
nix
.gitignore
flake.lock
flake.nix
go.mod
go.sum
main.go
readme.md
readme.md

twin #

twin watches tangled for mentions of a bot, and gives each one to an agent in a session in tarp daemon.

twin tails jetstream for sh.tangled.* records from the accounts you choose. it starts an agent in a new tarp terminal when a record mentions or replies to the bot.

if a session already exists in that context, twin types the new message into that terminal.

build #

nix build

or, in the dev shell:

nix develop
go build

usage #

configure the service using TWIN_* variables. twin config shows all of them with their defaults. nixos module is provided.

export TWIN_DIDS=did:plc:qfpnj4og54vl56wngdriaxug        # oppi.li
export TWIN_MENTION_DIDS=did:plc:omwbu2wmkfxrsevklxbxujfx # bot.oppi.li
export TWIN_MENTION_HANDLES=bot.oppi.li
twin
variable default
TWIN_DIDS accounts to watch. twin ignores all others.
TWIN_MENTION_DIDS the bot, in a record's mentions list.
TWIN_MENTION_HANDLES the bot, as @handle in a record's text.
TWIN_COLLECTIONS sh.tangled.* collections to read.
TWIN_OPERATIONS create add update to act on edits too.
TWIN_JETSTREAM_HOSTS jetstream.us-east.bsky.network,jetstream.us-west.bsky.network the first host, then failovers.
TWIN_TARP_ADDR 127.0.0.1:39423 the tarp daemon.
TWIN_AGENT_COMMAND exec opencode --auto --prompt "$TWIN_PROMPT" runs with sh -c in the new terminal.
TWIN_JOIN true send a mention to the terminal of its thread, if one runs.
TWIN_PROMPT_TEMPLATE a go text/template file to replace the built in prompt.
TWIN_STATE_DIR $XDG_STATE_HOME/twin the jetstream cursor and the prompts.
TWIN_WORK_DIR $TWIN_STATE_DIR/work one directory for each thread. the agent starts there.
TWIN_DRY_RUN false log the prompt, start nothing.

to test the agent on a single record, you can manually dispatch:

twin dispatch at://did:plc:qfpnj4og54vl56wngdriaxug/sh.tangled.feed.comment/3mxs4g5tc5kqs

the agent starts in workDir, as the tarp user, so let user be the user of the tarp daemon. environmentFile adds more variables. nix/module.nix has all the options.

the agent #

the agent gets the task in $TWIN_PROMPT, and in a file at $TWIN_PROMPT_FILE. these variables tell it where the mention is:

  • TWIN_URI, TWIN_CID: the record that mentions the bot.
  • TWIN_THREAD: the issue or pull of the record.
  • TWIN_KIND: issue or pull.
  • TWIN_REPO: the repository did, if twin found it.
  • TWIN_AUTHOR: the did of the author.

the tarp terminal also has the environment of the tarp daemon. put the bot credentials there, for example a goat login as the bot.