Skip to content

Set up an AI team

CLIAPIAdvanced~30 min

The payoff is provenance. When a pull request merges and someone asks "who wrote this, and why", you can go from the commit trailer to the worker, to its sessions, to the transcript on disk. Getting that is what this page is for; naming your AI coworkers is how it is done, not why.

A team is one or more role agents installed into your org as one App, with named workers ("Iris", a backend engineer) cast into it — plus the per-developer loop that attributes every coding session to a worker and to the human who drove it.

You probably do not have to run any of this yourself

This page is the commands. Most people get a team by asking a coding agent for one — see Set up an AI team with your agent, which covers what to ask for and how to check each step worked. Come back here when you want to run it yourself, or to check what your agent did.

Read the model first if you have not. Teams, workers, and sessions explains why a persona is dressing on an Agent, why a worker is a casting, and why a name is permanent — and two of the steps below cannot be undone, so it is worth the ten minutes. This page is the recipe.

Prerequisites

  • An organization in Hadron, and ADMIN or OWNER in it. Several steps here are org-admin operations.
  • The hadron CLI, v0.37.0 or later for this complete recipe, authenticated (hadron auth login). Check with hadron version; if it is older, brew upgrade hadron and check again. v0.37.0 is the floor for the recipe as a whole because hadron app join first shipped there; the other commands are older (app agent add v0.9.0, --install-into v0.13.0, agent compile v0.29.0, app member add v0.29.0, team session shed v0.30.0).
  • A git repository to work in — a coding worker's session binds to a git worktree, and you need one worktree per worker (see Step 5). A worker that writes no code needs no repository: it can run from a plain directory.

This page states no server version. If a command fails with "the CLI and server schema versions are out of sync" or "the server rejected a query this hadron build sends", check hadron version, upgrade the CLI, and if it still fails report the server's error message by name.

In the commands below, <org-id>, <agent-ref> and <app-ref> stand for the reference the previous command printed. Use what you were given; do not build one by hand.

Step 1 — Create a role agent and write its boot prompt

A role agent is an ordinary Agent carrying persona dressing — a role — and a boot prompt written as a template. The template uses {{worker.name}} and the other platform variables, which are filled for the worker at each bind; the template never names anyone itself.

Create the agent:

hadron agent create --org <org-id> --name "Backend Engineer" \
  --visibility ORGANIZATION \
  --persona-role backend-engineer \
  --json

Every Agent is born with a system memory. Read its ID back from the agent:

hadron agent get <agent-ref> --json

The field is systemMemoryId, an ID rather than a URN. It can be null; if it is, stop and check your access rather than constructing a <agent>-system name. Pass the ID to -m. If you want the memory's URN, hadron memory get <that-id> --json returns the row.

Write the boot prompt to a local file, boot.md:

You are {{worker.name}}, a senior backend engineer on the Platform Team. You
own the API layer and the data model. You read the specs before you write
code, and you say so when a request conflicts with one.

Add it to the Agent's own system memory at boot:source, with the role boot-prompt. Compile reads only that node, in that memory, with that role:

hadron node add -m <system-memory-id> --loc boot:source \
  --name "Backend boot" --role boot-prompt --content-file boot.md

Compile it, then read what it produced:

hadron agent compile <agent-ref> --json
hadron node get <compiledNodeRef> --json

<compiledNodeRef> and the revision come from the compile output. Compile is not approval. It writes a compiled revision and normally points the Agent at it, but it issues no approval, and a bind is refused until the compiled prompt is approved. Read the compiled node, then approve exactly the revision you read:

hadron node approve <compiledNodeRef> --revision <reviewed-revision>

If the revision changed since you read it, the approval is refused rather than applied to text you did not review.

A worker can fix its own prompt source itself, under a grant you sign; see Let a worker edit its own boot prompt.

If your organization requires signing

Where the App's organization has switched signing on and the deployment ships signing (required AND deploymentSigns, which the server reports as enforced), a person must sign that revision too. A new revision is not served until it is signed, and a bind is refused only when no approved and signed revision exists to fall back to. An organization that has switched it on where the deployment does not sign reads "required, but not enforced": nothing is refused yet. When enforced, the served revision is the latest that is both approved and signed. How an ADMIN or OWNER turns this on, and the preview they see first, is in Require signed boot prompts.

hadron node sign <node-ref> --revision <rev> only creates a signing request; the CLI never signs. A person completes it with their passkey on the server's signing page. Follow it with hadron node signing-request get <id>, and hadron node signatures <node-ref> shows who has signed. An agent may ask for a signature; it never gives one.

Repeat per role (frontend-engineer, reviewer, …). One detail matters: personaRole is the casting key. team worker cast --role backend-engineer finds the single installed agent whose dressing matches — zero or two matches refuse rather than guess.

Whitespace and unknown names in {{…}} are covered in Platform variables in a boot prompt. The platform does not check that a template binds the name (hasNamePlaceholder is retired and always null), so read the composed prompt in the rehearsal in Step 4 before you cast: a template that never binds the name produces workers whose prompt never names them.

Step 2 — Install the team, add the other roles, join

Install the first role agent as an App:

hadron app install --org <org-id> --agent <agent-ref> \
  --name "Platform Team" --urn platform-team-app \
  --type WORKSTATION --json

The App is a different entity from the Agent, and it gets its own reference. Use the one this command returns as <app-ref>. The App is also provisioned with its shared memory at install — the team space the group chat and worklog live in.

Install every additional role agent explicitly:

hadron app agent add <app-ref> <additional-agent-ref>
hadron app agent list <app-ref> --json

app agent list is the install roster, which is the cast pool. Nothing cascades from a "team agent": an agent is castable because it is installed in the App (or imported by one that is — see Cast an agent an installed agent imports). Instead of app agent add you can pass --install-into <app-ref> to agent create; that is two steps under one command, so if the creation succeeds and the install fails, attach the agent with app agent add.

Everyone who will drive a worker joins the App:

hadron app join <app-ref>

You join as yourself. The role you get comes from the primary Agent's membership policy and is never owner. Joining again returns your existing membership and exits 0. If the App is closed to self-join, or full, the server refuses and the CLI exits non-zero with the server's message. Ask someone who manages the App (its owner, a member with the owner role, or an org admin) to add you. They run:

hadron app member add --app <app-ref> --user <you> --role <role> --yes

hadron app member roles lists the roles they can give you, and --yes is needed when the command runs without a person at the prompt. See app member.

To find the App's shared memory, list its memories rather than guessing a slug:

hadron app memories <app-ref> --json

Step 3 — Role definitions (optional)

A role definition is documentation: it says a role exists, what it is for, and optionally which repositories it works in. It allocates nothing, and casting does not read it. The role or --agent you pass at cast time selects an installed agent directly, and a cast can use a role with no definition at all. Keeping the definition's slug identical to the agent's --persona-role is a convention that keeps the roster legible, not a lookup the platform performs.

Role definitions are read from an installed agent's system memory, so create them after Step 2:

hadron team role create backend-engineer --app <app-ref> \
  --team-agent <agent-ref> --description "Owns the API layer and the data model"
hadron team role list --app <app-ref> --team-agent <agent-ref>

Pass --team-agent with an installed agent explicitly. Without it the server looks across the App's installed agents for the one holding a roles branch and refuses when there are none or several.

There is no name register — names are chosen at cast time

Casting reads no system memory at all: you name the worker yourself (Step 4), a nameless cast refuses WORKER_NAME_REQUIRED, and per-App name uniqueness is what makes a name permanent. Agreeing names in advance is still worth doing — a name can never be re-minted, so two people picking the same good one means one of them loses it — but that is your team's convention, not something the platform enforces.

Role definitions through the API

teamRoles(appRef:) reads them; createTeamRole, updateTeamRole and deleteTeamRole write them. updateTeamRole also carries repos, the role's repository affinity, which the CLI has no flag for yet (hadron-cli#456). Omitting repos preserves it, [] clears it, and an explicit null counts as omitted. Affinity is a soft signal, never a gate: it lets a client warn that a worker is about to work in a repo its role does not own.

hadron api 'mutation($a: ID!, $r: String!, $repos: [String!]) {
  updateTeamRole(appRef: $a, role: $r, repos: $repos) { role repos }
}' -F a=<app-ref> -F r=backend-engineer -F repos='["acme/api","acme/schema"]'

Step 4 — Cast the workers

Casting creates the named team member — the one irreversible act in the feature, so rehearse it first.

team worker cast needs v0.10.0 or later

On v0.9.0 or earlier both commands below fail. That cast still sends teamAgentRef, which #1050 removed, so the dry run and the real cast both refuse with "the server rejected a query this hadron build sends" — the same hadron-cli#496 version floor as team role. Check with hadron version; the API calls below are the fallback if you cannot upgrade.

Rehearse through the API:

hadron api 'query($a: ID!, $r: String!, $n: String!) {
  castWorkerPreview(appRef: $a, role: $r, name: $n) {
    name role agentName prompt
  }
}' -F a=acme.com:platform-team-app -F r=backend-engineer -F n=Iris

Then cast for real:

hadron api 'mutation($a: ID!, $r: String!, $n: String!) {
  castWorker(appRef: $a, role: $r, name: $n) { id name role prompt }
}' -F a=acme.com:platform-team-app -F r=backend-engineer -F n=Iris

Note the preview is a Query returning its own type, so it takes its own selection set rather than a Worker's fields. Everything the rest of this step says about names, refusals and permanence is server behaviour, and applies to either surface.

hadron team worker cast --role backend-engineer --name Iris --dry-run \
  --app acme.com:platform-team-app

The dry run (castWorkerPreview on the API) runs the cast's exact resolution — same refusals, same authorization — and confirms the name you are claiming is still free, alongside the composed boot briefing, before the name is permanent. It reserves nothing: a previewed name may be gone by the time you cast.

Then cast for real:

hadron team worker cast --role backend-engineer --name Iris \
  --app acme.com:platform-team-app

--name is required (WORKER_NAME_REQUIRED without it): a name is permanent within the App, so it is chosen, never derived. The claim is one attempt — WORKER_NAME_TAKEN if that name is already used, including by a retired worker, since retirement never frees a name. The server then binds the template, provisions the worker's working memory, and prints the boot briefing. There is no per-worker prompt flag: the worker is served the compiled boot prompt its pointers select (its own, else its installed agent's, else the agent's; see Serving a boot prompt), and you change it by compile and approve (Compile a boot prompt). Check the staff:

hadron team worker list --app acme.com:platform-team-app

Names are permanent, per App — including retired ones

hadron team worker retire <name> --yes ends the casting but never releases its name — merged commit trailers and chat history reference it forever; a recycled name would silently repoint all of them. worker rm is the one escape, and it only works on a never-used miscast (WORKER_IN_USE otherwise). Two different Apps can each have an Iris; within one App the claim is case-insensitive and permanent.

Approve the workers' boot prompts in one run

When several workers have a compiled boot prompt waiting for approval, one command previews them all and approves the ones you choose. It is a terminal command, and you run it as the person who manages the App. You need CLI 0.41.0 or later (0.42.0 for --as-worker).

hadron team worker approve

With no flag this only previews: nothing is sent. It lists each worker as to approve, already approved, tampered, skipped or unknown, with the compiled node and revision. Read the list, then send the approvals:

hadron team worker approve --apply
hadron team worker approve --only Iris,Theo --apply   # just these workers

--apply does not approve what an earlier preview showed you: it reads the workers' current prompts again in that same run, then sends one approval per to approve worker, in roster order, each pinned to the revision it just read. If a prompt changes after your preview but before you run --apply, the run approves the newer revision, which you have not reviewed. Run the preview and --apply back to back, or approve a reviewed revision on its own with hadron node approve <ref> --revision N. A worker whose prompt changes during the run, after that read, is refused REVISION_MISMATCH; run it again. A refusal for one worker does not stop the others, and there is no rollback: the approvals already sent stand. Nothing is signed; where your organization requires signing, a person still signs each compiled prompt (Require signed boot prompts).

A worker is selected only if it has its own compiled prompt (an Agent's or install's prompt does not count), its target is not deleted, and the prompt is not yet approved or has been superseded by a later edit. After each approval the command reads once what a serve would give that worker at that moment, for example "a serve now would give rev N". That is a snapshot, not a promise about the next bind.

Two outcomes need you, not the command:

  • Tampered. A prompt whose integrity check reports tampering is never approved in a batch, and the run exits 5. Investigate it, then approve it on its own with hadron node approve <ref> --revision N.
  • Encrypted memory. A prompt in an encrypted memory cannot be approved this way. It is skipped and never sent, but the run still exits 5, so a script does not read the batch as done.

The exit code is the highest across the workers: 0 when everything selected is approved or nothing is pending; 5 for REVISION_MISMATCH, NODE_IS_PLACEHOLDER, an encrypted-memory skip or a tampered row; 8 when the server refuses the approval; 7 when a response was lost (the worker is reported unknown with outcome landed, not-landed or unknown, and the approval is never sent again); 4 for an --only worker that is not live in the App; 1 for a row whose state the command could not decide. Any other approval state also lands in unknown with exit 1. Approve that prompt on its own with hadron node approve. The reference entry lists the --json shape.

Who can run it

By default the server decides, per worker: whoever manages the App, acting as themselves. A worker session is refused BOOT_PROMPT_WORKER_SESSION_REFUSED, and anyone else BOOT_PROMPT_APPROVAL_FORBIDDEN (both exit 8). With --as-worker, the worktree's bound worker approves instead, and the server admits only prompts named by a signed bootprompt.compile.approve grant; see Let a worker edit its own boot prompt.

Cast an agent an installed agent imports

You do not have to install each role agent to cast it. An agent that an agent installed in the same App imports directly counts as installed for casting, and no install row is written for it. It is an alternative to installing each role agent with app agent add in Step 2, for an agent that is already imported by an installed one.

# The roster shows each agent's install method and, for a derived one, its importer
hadron app agent ls acme.com:platform-team-app

# Cast the imported role agent; the role comes with the agent
hadron team worker cast --role backend-engineer --name Iris \
  --app acme.com:platform-team-app

What holds, as built:

  • Direct imports only. One level: the importer must itself be installed in the App, and an import of an import does not count.
  • Required and optional imports both count.
  • Installed wins. When an installed agent and a derived one share a role, the installed one is the one a cast by role picks, so the --role cast above casts the derived agent only when no installed agent has that role. To cast the derived one anyway, use --agent <agent> instead of --role. Two derived agents with the same role are ambiguous (WORKER_AGENT_AMBIGUOUS): pass --agent.
  • Two importers are fine. If two installed agents import the same agent, it stays castable until the last qualifying import is gone, and for as long as the organization's licence holds.
  • The App's organization needs its own licence. The importer's grant is never borrowed. An agent from another organization is derived only while this organization holds an active grant for it; an agent of its own organization needs no grant on file, but a revoked or expired one is not reactivated.
  • Customizing a derived agent creates its install memory, not an install row. The agent stays derived.
  • An explicit install makes it permanent. hadron app agent add <app> <agent> writes the row and keeps the agent installed after the import is removed. It takes the same permission as any install.
  • Removing an import leaves existing workers alone. The workers keep their names and history, as after any uninstall. Once no installed agent imports the agent any more, it can no longer be cast, unless it is installed.
  • Only an organization's App. An App owned by a person has no derived installs.

hadron app agent ls needs a CLI that contains hadron-cli#1681 (first shipped in release v0.37.0; v0.35.0 does not have it) and a server containing hadron-server#3446 (merged at d0b374cd). The cast itself works on a server with hadron-server#3443 (merged at cdd8d420). The column and the rules are in the CLI reference. The rules behind this are in Installed, and derived from an import.

Step 5 — Run a worker session

This is the loop each developer repeats.

One git worktree per worker

Before the first session start, get the layout right — this is a setup decision, and by the time it announces itself you have already arranged your machine the wrong way.

Never run two workers, or a worker and an unbound agent, in the same checkout.

One checkout means one index and one working tree. Two agents in it are editing shared mutable state, and neither can see the other: whichever commits with git add -A or git commit -a silently absorbs the other's in-flight edits into its own commit. Nothing in git status distinguishes "my edit" from "somebody else's edit made ninety seconds ago", and no lock or warning exists.

Give each worker its own worktree:

git worktree add -b feat/rate-limits ../api-iris

Separate index, separate working tree, shared object store — the sessions stop being able to collide. The CLI already stores the binding under the worktree's resolved git dir, so linked worktrees each get their own; the tooling supports this today, it just doesn't teach it.

Why this matters more than tidiness: binding a worker exists so a merged PR traces back to the session that produced it. A swept file lands in the wrong PR, under the wrong worker, and severs that link with no signal — the one thing the provenance chain is for.

What it looks like when it happens, so you recognise it instead of filing a data-loss report: files vanishing from git status mid-task, and edits you did not make appearing in your diff. Nothing is usually lost — check git log origin/main and git log -S '<a phrase from your edit>' before concluding otherwise.

If you must share a checkout, never git add -A / git commit -a — stage the paths you actually touched, by name — and re-run git status immediately before committing, not once at the start.

Start the worker session in the git worktree you are about to work in:

hadron team session start --as Iris \
  -m "$TEAM_MEM" \
  --repo acme/api \
  --branch feat/rate-limits \
  --tool claude-code \
  --model claude-opus-5 \
  --transcript ~/.claude/projects/acme-api/session-8f2.jsonl

That records the worker session server-side with its provenance (the session binds the worker; the server stamps the role agent and the App itself), prints the worker's boot briefing, and writes a binding under this worktree's git dir. The binding is what makes the worker session survive your coding agent losing its context — or your chat session ending:

hadron team session whoami    # what this worktree is bound to

A worker that needs no repository

A worker that writes no code (a coordinator, a reviewer of documents, a reader of chat) can run its session from a plain directory, with no git checkout. Make an empty directory for it and run the same session start --as from inside it. The binding is kept in a hidden .hadron-team/ directory inside that directory instead of under a git dir, and the server still holds the real binding. session start (including the resume, start with no worker named), session shed, session resume-claim and session end work from there, whoami reads the cache and otherwise the server, and recovery after a compaction is the same.

  • Needs hadron-cli v0.44.0 or later. It is the first release to contain hadron-cli#1968; v0.43.0 and earlier do not. Check with hadron version.
  • One worker per directory. Another worker's session start in the same directory is refused (--force does not change that), so give each worker its own. Git worktrees behave as before.
  • To free a directory, end the session in it. Run hadron team session end from inside the directory (add --handoff to leave a note for the next driver). It removes the local binding, and the directory is unbound. It also clears a binding whose session was already ended elsewhere. Details are in the CLI reference.
  • Run from that directory itself. Only the bound directory counts, never a parent: a subdirectory is not bound.
  • Do not git init it. Turning a bound plain directory into a repository hides its local binding copy: the CLI no longer finds it. The server binding is untouched and whoami falls back to the server, so recover with a resume claim as in Recover after a context compaction.
  • Wakes are not promised. Ticker and router pushes for a worker without a checkout are not documented as working until hadron-server#4091 lands.

After a compaction or any context reset, don't start again: re-run hadron team session whoami, which reads the worker and session from the binding (and asks the server if the binding is gone). Add --check to also ask the server whether the session is still open. To reset a context on purpose and keep the session, run hadron team session shed. Both are covered in Recover after a context compaction.

-m names the team memory — the worklog home, remembered in the binding so later commands don't repeat it. Log milestones as they happen, and close out when the work stops:

hadron team session log --pr 412 --action opened
hadron team session log --commit a1b2c3d --action pushed
hadron team session end --handoff-file ./handoff.md

--handoff is the one that matters, and it is not --summary. A handoff is the continuity record the next driver actually reads: what landed, what is open, what is blocked, what not to repeat. The server files it in the worker's own memory and hands it back at the next bind, unasked — and because handoffs follow the name, the next driver may be a colleague rather than you.

--summary is a different field and the next driver never sees it: a display-only label on the session row. If you are writing one thing for whoever comes next, write --handoff.

hadron team session end --handoff "PR #412 open awaiting review; do not re-run the migration."
hadron team session end --handoff-file ./handoff.md   # a paragraph, without shell quoting
hadron team session end --handoff -                   # from stdin

Omitting it entirely is the normal way to end without a record. An explicitly empty handoff is refused (exit 2) — somebody meant to write something. The write happens before the session ends, and a failed write refuses the end (HANDOFF_WRITE_FAILED) rather than ending anyway: a still-bound worker is recoverable, an ended session whose handoff evaporated is not.

--handoff needs v0.11.0 or later

It shipped in v0.11.0 (hadron-cli#505). On v0.10.0 and earlier session end has only --summary, so the CLI track cannot write a continuity record at all and the next driver of that worker inherits nothing. Check with hadron version and upgrade.

If you are stuck on an older CLI, leave what the next driver needs where they will find it — a worklog record (session log) or a team-chat post.

session end clears taken — it does not release the name

Closing your editor, archiving your chat session, or letting the coding agent stop does not end the worker session. The worker stays taken, and the next person to pick it up gets a WORKER_TAKEN prompt with your name on it for work you finished yesterday.

And ending the session is not the same as giving the worker up. Since server#1050 the name is held by you until an explicit releaseWorker — a hold that survives session end, expiry and going idle. If a colleague wants to drive Iris, either you release her or they cast their own worker; waiting is not the answer.

The WORKER_TAKEN prompt itself does stop after about a day — the session stops reading as live once nobody drives it. That unblocks your own next bind and nobody else's: the hold above is untouched, so your colleague still meets WORKER_HELD. And the session is not ended and your handoff is not written — going quiet closes nothing. A worker session ends only by an explicit session end, because a newer session on the same worker replaced it, or at a hard expiry promised at start (which a worker session has none of). See the two kinds of session.

If another terminal ended the session you are still bound to

Two terminals can share one worker session, for example when a fresh context resumed it in a second worktree. If one of them ends the session, the other worktree's binding still names it. Its next hadron team command that uses the binding prints a warning to stderr and then runs as usual: which session, when it ended, why, and the command to rebind.

warning: this worktree's worker session <id> (worker Iris) ended at <time> (cause: ended). This command still runs. To work as this worker again, rebind this worktree: hadron team session start --as <worker id> (a plain start replaces an ended binding; no --force needed)

The cause is one of ended (someone ran session end), superseded (a newer session on the same worker replaced it) or expired (a hard expiry). A session that ended before Hadron recorded causes reads unknown; Hadron does not guess one, and it does not record who ended it. For superseded, the warning sends you to hadron team session list --as <worker> --active first: the newer session may be live, and then a plain start refuses. If the CLI cannot check (no network, or the binding belongs to another server) it says note: could not check … and never claims an end. Rebinding takes your own worker back; it does not need --force, and it does not remove the other worktree's binding file or end its agent. This warning comes with CLI v0.25.0 (19 October) and later (hadron-cli#915).

The bare 412 works because the CLI qualifies it from the session's --repo; the stored ref is the canonical acme/api#412. Kinds are --pr, --issue, --commit, and --branch.

Let the coding agent run these itself

session start, log, and end are three commands an agent can run at the right moments if you put them in its instructions. whoami is cheap to re-read after a compaction or context reset.

If the worker is unavailable — taken, or held

Two different things stop you binding a worker, and since server#1050 they have different answers. Getting them confused is what once let an agent end a mid-PR driver's session and bind as them, following the documented procedure at every step.

Taken Held
Means a live worker session is bound the name belongs to a person
Set by session start the first bind — casting does not hold
Cleared by session end, or the idle window passing only an explicit release
Your move it is a question about your own worker ask the holder, or cast your own

Held is the one people get wrong. A hold survives session end, expiry and going idle — that is the point of it. "Wait and it'll free up" is true of taken and false of held, so if the worker you want belongs to someone else, waiting achieves nothing.

Casting does not create a hold. A worker is born unheld and the first bind claims it — which is what makes the normal flow work, where a coordinator casts a roster that other people then pick up. If the caster held every name, everyone would be blocked on a release they should never have needed.

If a roster does not show who holds a name, do not assume it is free. Holder details have their own visibility rules; see holder fields and visibility for the GraphQL projection and the CLI's current limits.

For a taken worker, session start --as refuses with WORKER_TAKEN, shows who last drove it and when they were last seen, and proceeds only on an explicit --force — informed and deliberate, never silent. Two situations produce that refusal, with different fixes:

  • This worktree is already bound — if the old session has ended or lapsed, a plain session start replaces the binding. If it is still live, end that worker session first, or --force replaces the binding (ending the worker session the old binding named, best-effort). Note --force relabels the binding; it does not separate two agents sharing one checkout — for that you need a worktree each.
  • The worker has a live session elsewhere — someone (possibly you, on another machine) is driving it. Live means driven inside the idle window (24 hours by default — a deployment setting, not a platform constant), and any team tool or command that drives the session counts as activity, not just session log: reading or posting to the chat, listing workers and recording work all count (when a session goes quiet). Since server#1114 a session that is merely open no longer raises this refusal, so TAKEN means somebody drove it recently — not that somebody once forgot to close it. --force takes over; it does not end anyone else's session. Note TAKEN is only ever a question about a name already yours: a name held by somebody else refuses HELD before liveness is consulted at all.

--force reaches taken and never held — this is enforced, not etiquette. The hold is checked before the flag is even consulted, so session start --as on a name held by somebody else refuses WORKER_HELD (exit 5) whether or not --force rides along, and says so: "a held name is not freed by a worker session ending, and this cannot be forced — cast your own worker instead." The refusal names the holder, so you know who to ask.

It refuses every principal but the holder, including an App key — an App key is not a person and holds nothing, so it is never the right one. Reach for --force when the stale binding is yours; for somebody else's worker the answer is a release or a worker of your own, and the platform will not let it be anything else.

Releasing a name

A held name is freed by a release — and by nothing else:

hadron team worker release Iris --app acme.com:platform-team-app

worker get shows who holds a name. The line is omitted rather than dashed when there is no visible hold, and there is deliberately no held boolean: a hold you cannot see and a name nobody holds look identical from outside, and a boolean would answer "no" to a reader who merely lacks visibility.

Needs v0.10.0

hadron team worker release shipped in v0.10.0 (hadron-cli#495). On an earlier CLI (hadron-server#1060) go through the API:

hadron api 'mutation($w: ID!, $h: ID!) {
  releaseWorker(workerRef: $w, expectedHolderUserId: $h) { name heldByUserId }
}' -F w=<worker-id-or-urn> -F h=<the-holder-you-read>

Pass expectedHolderUserId. It asserts the hold you are ending is the one you looked at, so a hold claimed between your read and your write refuses WORKER_HOLD_STALE instead of being force-released silently — which is the outcome this whole section is about. Use expectUnheld: true when you believe nobody holds it. Omitting both is still accepted and still races.

Two principals may call it, and they are different acts:

  • The holder, releasing their own name. They owe nobody notice.
  • An App or org ADMIN, force-releasing somebody else's — the path that exists so a departed colleague's names are not held forever. An admin release posts to the team chat, naming who released what and from whom, because the situation it answers is precisely the one where notice was owed and there was no way to give it. The CLI prompts before this one unless you pass --yes. The chat post is best-effort server-side: an unreachable chat never blocks the release, so the receipt says a notice was posted rather than proving one arrived.

Releasing is narrow, and deliberately so. It does not retire the worker, does not free the name for a different casting, and does not touch history — the name stays permanently allocated to this casting, and the worker's working memory and handoff notes travel with the name to whoever holds it next. That transfer is the point — and the reason nothing private belongs in a worker's memory.

It is idempotent, but it will not tell you a name was free. A hold you may not see and no hold at all are indistinguishable from outside, so releasing reports no visible hold rather than "unheld" — do not read that as permission, or you will meet WORKER_HELD at the next session start.

Check who's actually working before you force anything:

hadron team session list --active

Step 6 — Carry the worker into the PR

The link from a merged PR back to the worker is a commit trailer carrying the worker's portal URL, which embeds the app-qualified worker URN — a PR is a context-free surface, and worker names are only unique per App. hadron team worker get prints this same URL:

Add rate-limit middleware to the public API

Worker: Iris (backend-engineer) <https://hadronmemory.com/app/u/hrn:worker:acme.com:platform-team-app:iris>

Use a trailer rather than a branch name or a PR title, because a trailer survives a squash-merge. Worker: follows git's Token: Value convention, mirroring Co-Authored-By, so git interpret-trailers reads it — provided it sits in the same trailing block as your other trailers. A blank line between them puts Worker: in an ordinary paragraph and git stops seeing it; git interpret-trailers --parse on your own message is the check.

The trailer line your worker is told to use comes from a per-worker template that an App manager can change; see Worker signature and trailer.

This replaces the older Persona: <app>/<Name> form

That spelling named a concept that was renamed — a persona is dressing on an Agent; the named identity is a Worker — and it omitted the org root, so two orgs with an App of the same slug produced identical trailers for different people. Trailers already merged are history and are not rewritten. Walk the chain from either end:

hadron team session list --as Iris --limit 20 --json   # what has Iris been doing?
hadron team session list --pr acme/api#412 --json      # who wrote this PR?

Both PR spellings (acme/api#412, the full URL) return the same rows — refs normalize to one canonical form. Expect several rows for a PR of any size: three sessions on one PR means three transcripts, and all three are part of the answer. Each row carries the driving human, the tool, the host, the model, and the transcript path.

What you have now

  • A named staff, permanently claimed per App — every name chosen at cast time, and team worker list --include-retired the roster of what is already gone.
  • Every coding session attributed to a worker and to the human who drove it, with tool, host, model, and transcript path — and informed takeover when two humans want the same worker.
  • An append-only worklog joining artifacts to sessions, queryable from either end.
  • A group chat the workers coordinate in — hadron team chat post|read, with @worker-name mentions.
  • Read-time liveness: a crashed session stops reading as live after its idle window, so its holder can bind that worker again without forcing a takeover of themselves — and without the session being ended out from under a driver who was merely quiet. The name's hold is untouched, so this frees nothing for anybody else.

See it in the portal

Everything above is readable in the browser, on the App's page — useful when the person who needs to see it isn't the person driving a session.

Open the App (Apps → your team App). Four tabs matter here, and each is addressable, so you can link someone straight to one:

Tab What it shows
Chats Every conversation the App has, behind one selector: the team chat, the agent chat, and any 1:1 chats. The team chat is the thread the workers coordinate in — the same messages hadron team chat read returns, each post showing whether a worker or a person wrote it, its seq, and any @mentions. You can post to the team chat from here; a browser has no worker session, so your post is attributed to you, not to a worker. Other chats are read-only in the portal.
Worklog The append-only artifact↔session join. Filter by artifact, kind or tool; the filters are in the URL, so a filtered view is a link you can paste into an issue.
Worker agents The workers cast into this App, with their roles and working memories. Retired workers included — their names stay claimed. Its ?tab= value is still staff — see below.
Memory The installed agents' memories, including any role definitions.

Every tab takes the same ?tab= parameter — chats, worklog, staff, memory, settings (an unrecognised value just opens the App's default tab). The Chats tab takes a second parameter, ?chat=, so you can link to one conversation rather than to the tab:

/app/apps/<appId>?tab=chats&chat=chats:team
/app/apps/<appId>?tab=worklog

The older ?tab=team-chat and ?tab=chat links still work — they open the Chats tab with that conversation selected — so anything already pasted into an issue keeps resolving.

The Worker agents tab is still ?tab=staff

The label changed; the value deliberately did not. A tab's ?tab= value is an address — those links are shared in issues and messages, and since they now survive the URN resolver there are more of them in circulation, not fewer. Renaming the value would break every one of them, and it would break them silently: an unrecognised ?tab= just opens the default tab, so the page still renders and the reader concludes the feature moved.

So a mismatch between what a tab is called and what its parameter says is the intended state here, not a typo in this table.

Two things the portal deliberately will not let you do, because the team chat and the worklog are records rather than working documents: there is no delete or rename on either, and nothing runs a model turn against the team chat. Correct a wrong worklog row by recording a newer one.

Looking up which sessions produced a PR is the worklog's main job, and it takes any spelling of the ref — paste the GitHub URL or type the short form, both resolve to the same records:

/app/apps/<appId>?tab=worklog&worklogRef=owner/repo%23371

Several rows for one artifact is the expected result, not duplication: a PR worked across three worker sessions is three records and three transcripts. That spread is the answer.

How many workers those sessions represent is a separate question — one worker driven across three sequential sessions produces the same three rows as three different workers would. The workerName on each row is what tells you which.

Phone widths

The App page isn't responsive yet — on a narrow screen the navigation doesn't collapse and the content runs off the side (hadron-portal#740). Use a desktop browser for now.

Troubleshooting

Symptom Cause
WORKER_NAME_TAKEN on an explicit --name The name is claimed in this App. Pick another; team worker list --include-retired is the roster of what's gone — without that flag a retired worker holding the name doesn't appear, and the refusal looks unexplained.
WORKER_NAME_REQUIRED from a cast A name is never derived — pass one. There is no register to fall back to (step 3).
"the server rejected a query this hadron build sends" from team role or team worker cast The CLI/server skew from #1050, not a mistake of yours. Check hadron version and upgrade to v0.37.0 or later. If you cannot, the GraphQL calls in step 3 and step 4 are the fallback. hadron-cli#496 is where the team role and team worker cast fix shipped.
WORKER_AGENT_AMBIGUOUS Two agents of the same kind carry the same personaRole: two installed ones, or, when no installed agent has the role, two derived ones (cast an imported agent). An installed agent and a derived one never collide; the installed one wins. Pass --agent to pick one.
WORKER_AGENT_NOT_INSTALLED from an explicit --agent The agent exists but is neither installed in this App nor derived from an import, and casting requires it installed at cast time. An agent that an installed agent of this App imports directly also counts, while this organization's licence for it is usable: an active grant, or no grant on file for an agent of its own organization. A revoked or expired grant stops it counting (cast an imported agent). Add it to the existing App — hadron app agent add <app> <agent> — then cast; you do not need to rebuild anything. Installing takes a narrower permission than casting, so if you are a plain App member you can hit this and be unable to clear it yourself — ask the App's owner or an org CONTRIBUTOR+ to install it. Distinct from WORKER_AGENT_NOT_FOUND, which means no installed or derived agent matched the --role you gave.
SESSION_NOT_WORKER_BOUND The session was started without a worker, and you are doing something only a worker can do — writing a handoff at session end, or posting to the team chat as a worker. The work is not lost: end without a handoff, or post as yourself. Bind next time with --as <worker>.
CHANNEL_HOST_NOT_WRITABLE when posting to the team chat as a worker The worker is not this chat's App's — it belongs to a different App, or the chat has no host App — and you, as the session's driver, may not write the chat's host memory. Post as yourself (--as-me), bind a worker of the chat's own App if it has one, or ask for write access to the chat's host memory.
session start --as refuses with WORKER_TAKEN The worker has an active worker session. See if the worker is unavailable.
session end refuses with exit 2 The binding was created against a different --server than the one you're pointed at now.
The binding is gone but the session is still open hadron team session end --session <id> — the recovery path (also for a binding written by a pre-Worker CLI). Find the id with hadron team session list --active.
SESSION_NOT_IN_APP on a worklog write -m named a different App's memory than the bound worker's App — a mismatch to fix, not a session to restart.
hadron app join exits non-zero The server refused, and the CLI prints its message and does not map it to a fixed code. Common causes: the App is closed to self-join, it is at its member cap, or the primary Agent offers no member roles. Ask someone who manages the App (its owner, a member with the owner role, or an org admin) to run hadron app member add --app <app-ref> --user <you> --role <role> --yes (hadron app member roles lists the roles). Joining an App you already belong to is not a failure; it returns your existing membership.
agent get --json shows systemMemoryId: null The Agent has no system memory you can use. Stop and check your access; do not construct a <agent>-system name.
A bind is refused after you compiled the boot prompt Compile does not approve. Read the compiled node and run node approve --revision <reviewed>. If your organization requires signing and the deployment ships it (enforced), a person must also sign that revision (step 1; require signed boot prompts).
A teammate can't end a session you started Correct behavior. Only the attributed user, the App as a pure App-key principal, or a platform admin may write a session. See Session access.