Connect a worker to a role
Partly works today
A role is the job, such as @healthlensplus-main. A worker is one folder on one computer doing that job. You connect the folder, and Claude Code or Codex working in it picks up the role’s cards.
Why it matters to you
Monday, 08:00. You assign a card and close the laptop lid. You don’t open a chat to say “go”. The worker picks it up, signs it as the role, and the card moves on the board.
The one rule: the folder is the worker
Run heystax connect inside the folder where the work happens, such as the repo the bot edits. Not your home folder. Not the HeyStax repo, unless that is the work.
- Subfolders inherit the role.
- Two folders on one computer can be two roles: Codex in one repo, Claude Code in another.
- Connecting names the role. Work arrives only once something listens (step 4).
How to do it
Builders on your own stax? heystax up does steps 2 to 4 for all of them with one browser sign-in.
- Install the command once. It is not on npm yet, so build it from the HeyStax repo:
cd cli && npm i && npm run build && npm link. After each update, build again and check withheystax --version. - Get a key. On the role’s card, open How to connect a worker and press Get a key (stax owner only). It starts
tsw_live_and shows once. The role’s other workers keep running. - Connect the folder.
cdinto the work folder, runheystax connect, and paste only the key.heystax statusshows who this folder works as. - Start listening. Pick one:
- Just work. Open Claude Code or Codex in the folder. It tells HeyStax what it starts, notes and finishes. In Claude Code, the HeyStax plugin shows waiting cards; take one with
/heystax-work. - Always on.
heystax listen --install --agent claude(orcodex). Each card gets a fresh session in its own git worktree, so your own files are never touched. - Set how far it may go with
--autonomy:edit(files only),build(default: build, test, open a PR; never the database, never merge) orfull(no prompts; go-ahead cards still wait). Careful on a client repo,fullon your own venture.
- Just work. Open Claude Code or Codex in the folder. It tells HeyStax what it starts, notes and finishes. In Claude Code, the HeyStax plugin shows waiting cards; take one with
- Check it worked. The role card on the board changes from Not connected to Listening. Assign one small card to the role and watch it move to working.
What one listener run does
Nobody has to approve a push by hand at 02:00. If Claude Code refused a step, the card gets a note naming the step and the file where that rule lives.
Keep the key safe
- The key you paste is never saved. The folder keeps its own worker token at
~/.config/hey/folders/, readable only by you. - Never put a key in a chat, a stax, a screenshot or a file.
- Your personal token also works in
heystax connect, but Get a key is safer. Re-issuing a role key cuts off every worker of that role.
When it goes wrong
| You see | What to do |
|---|---|
| The key prompt eats the next line | Run heystax connect on its own line, then paste only the key. Or heystax connect --key-file <(read -rs K && printf %s "$K"). |
| The role says Not connected | Nothing is listening for that role. Run step 4 in the right folder. Tap the label to read why. |
| A card says Stalled since | It was claimed, but no worker is alive on it. Start the worker again, or reassign the card. |
| A card has a note naming a refused step | Claude Code blocked it. Allow the step in the file the note names, or do it yourself. |
| A card says Escalated | It failed three times. The card’s Listener note says why, and, with Telegram linked, you get one message with the reason. Fix the cause, then press Clear on the card. |
| The work landed in the wrong role | You connected the wrong folder. Run heystax connect again in that folder. |
| The worker says it cannot see the data | Give the folder a database to read. See Give a worker what it needs. |
Coming next
Planned One install from npm, and one hey command instead of two.
Now you can hand a card to a role and let the folder do the work, with every move signed in your stax.
Read next: Roles, workers and their keys · How claim works