Hire roles, then give them workers
Partly works today
A role is a job on a Stax, such as @waymarks-bizdev. A worker is whatever does that job right now: Grok Bot, Claude Code on your laptop, Codex on a server. You keep the role. You can swap the worker.
Why it matters to you
You fire a bot on a Friday. On Monday a different one picks up the same role. It has the same mission, the same open actions and the same history, and you didn’t re-explain anything.
Each key opens only what its holder needs, so your own key never sits inside a bot.
Watch it work
Eight short scenes. Your key makes the Chief. The Chief creates roles, at most 10 per Stax, and can’t hand on its own grants. Each role enrolls one worker per machine, and you can cut off one worker without touching the rest. A hosted bot is woken by a signed push that carries only IDs and retries at 1, 5 and 30 minutes. A worker on your own machine runs heystax listen, which waits for work over an outbound connection and starts Claude Code or Codex on the card in its own git worktree. When a run ends, a queue empties or nobody is home, the Chief hears about it. Irreversible work waits for a go-ahead, and the Chief can’t give one on its own proposal. The last scene, heystax connect, sets up a folder as a worker of one role.
Three keys, four holders
| Key | Who holds it | What it can do |
|---|---|---|
| Your personal access token | You, and nobody else | Everything you can do. It registers roles and sets their access. |
| A role token | The role’s owner, usually your Chief of Staff | Acts as that role on the Stax you authorized it for. Enrolls workers. |
| Your Chief of Staff | A role token with two extra grants on a Stax: manage_roles and go_ahead | Everything a role does. Creates roles. Gives the go-ahead on irreversible work it didn’t propose. |
| A worker token | One machine or one bot | Acts as the role, under the role’s limits. It can’t enroll other workers. |
Each token is shown once. It goes straight into the bot’s secret setting, for example its MCP bearer-token header. Never put it in a chat, a Stax, a screenshot or a file.
Find a bot still using your key
A bot on your personal key writes as you. Ask any HeyStax client to call owner_key_usage: it lists each app still writing with your key, its last write and the stax it touched. heystax-cli is your own terminal. Anything else is a bot to move to its own role key. Nothing is blocked, and each such bot is told how to switch.
How it works today
- You: with your own token, call
agent_registerto create the role, thenagent_authorizeit on your Stax (read,workorfull). - The role: with its role token, calls
stax_joinand says what it is accountable for. - Each worker: the role calls
worker_registeronce per machine. That machine gets its own worker token. - The worker: starts a run, claims a Next Action and reports on it. If the machine dies, its claim is released when the run stops sending heartbeats, so the action doesn’t stay stuck.
- You: see every claim and report under the role’s
@handle, along with which worker did it.
To remove a worker, end its access. The role and its other workers carry on.
Let your Chief of Staff hire roles
Grant your Chief of Staff one permission per Stax, manage_roles. You do it once, with your own token: agent_authorize with manage_roles: true. After that, the Chief creates new roles with role_create and never needs your key.
- A new role never gets more access than the Chief has on that Stax.
- It works on that one Stax only, and its access ends when the Chief’s does.
- A Chief can create up to 10 active roles per Stax.
- Every role it creates is recorded as created by the Chief. You can end any of them.
- The Chief can’t pass
manage_rolesorgo_aheadon. Only you can grant them.
The chain is: your key → Chief of Staff → role → workers. You set direction. The Chief staffs the work.
Blockers stop at the Chief, not at you. The Chief also hears when a run ends, a queue empties, a card fails three times or work waits on a role with nobody home. It hands out the next step toward the goal.
How work reaches a worker
| Worker | How it hears about new work |
|---|---|
| A hosted bot, such as Grok Bot | A signed wake to its push URL, carrying only IDs. Retries at 1, 5 and 30 minutes. push_deliveries_list shows every attempt. |
| A worker on your machine, such as Claude Code or Codex | Partly works today |
heystax listen takes the next card with work_next and starts the agent in its own git worktree. Your machine only makes outbound calls. Install it from the repo for now. |
You can pause a launcher or cap its runs per hour.
Irreversible work, such as a production migration, waits for a go-ahead from you, or from a Chief you granted go_ahead. Never on work the Chief proposed or holds.
Connect a worker
| You want | Read |
|---|---|
| A bot in an AI app, with no key to copy | Connect a bot by sign-in |
| Every builder role on this computer, one command | Start every builder with one command |
| One folder as one role | Connect a worker to a role |