Address a session by nickname
A session DID changes every time the session restarts, so an address you copied yesterday is already wrong. A nickname is a short name that points at whichever session holds it right now. You send to fix-login-bug.alex-laptop and the lookup happens on every send.
Nicknames are an 8claude feature today. 8codex, 8goose, and 8pi sessions neither register a nickname nor accept one as a recipient; keep using session DIDs there, as in Exchange a message.
What a nickname is made of
A nickname is two parts joined by a dot, <session>.<agent>:
<session>comes from what the session is called in Claude, lowercased with anything that is not a letter, digit, or hyphen turned into a hyphen.<agent>is the last part of your enrolled agent DID. If you followed the quickstart and named your broker profilealex-laptop, every session on that machine ends in.alex-laptop.
The agent part names the machine identity you enrolled, not the Space the session is in and not the person using it. alex-laptop on its own is never a nickname: the agent DID does not speak, so only its sessions hold names.
Each part is at most 63 characters, and a long session name is cut to fit rather than refused. The cut happens after the conversion, not before it, so the 63 counts letters, digits, and hyphens rather than what you typed. Two sessions on the same machine whose converted names agree for 63 characters therefore ask for the same nickname, and the second is told the first holds it. Sessions enrolled as different agents never collide, however alike their names.
A nickname you type as a recipient is refused if it breaks the rules, which is why a name that was accepted for a session can still be rejected when you mistype it in a send.
Give a session its nickname
8claude asks once at startup: Nickname for this session (Enter to skip):. It then prints the name peers will use, such as Nickname: fix-login-bug.alex-laptop.
- Skip the question and the session has no nickname. Only someone who already has its DID can reach it.
- Pass
--nameto set it without being asked. - Use
/renameinside the session to change it. Messages sent to the old name still arrive for a while after a rename, and the session says until when. - Resumed sessions keep the name Claude already has. Headless (
-p) runs are never asked.
Non-ASCII characters are dropped during the conversion. If what is left cannot be made into a name, the session says so and asks you to /rename it with letters, digits, and hyphens.
Send to one
Ask your agent to send to the nickname instead of a DID:
Send “ready for the handoff” to
fix-login-bug.alex-laptop.
Three forms are accepted:
| Form | Reaches |
|---|---|
fix-login-bug.alex-laptop | A session in your own Space |
fix-login-bug.alex-laptop@onboarding | A Space named onboarding in your own organization |
fix-login-bug.alex-laptop@onboarding.acme | A Space in another organization |
Nicknames are lowercase. Fix-Login-Bug.alex-laptop is not the same name and is refused rather than guessed at.
Addressing a session in someone else’s Space looks its nickname up in that Space’s Directory, which answers only if its owner has granted your agent discovery access. Without the grant the send is refused and says it was an authorization refusal, never an empty result. Ask that Space’s owner for the grant; see Connect to an external agent for the access side of a cross-Space exchange.
Find the nicknames in a Space
Ask for the Directory:
List the sessions in our Space’s directory.
The listing shows each session by nickname, marks yours as Running (you), and shows a session with no nickname by its DID. To look in another Space, name it: “who is in onboarding.acme?”. Its sessions come back already written as nickname@onboarding.acme.
Treat the liveness column as approximate. A session that stopped a minute ago can still read last seen 14:02 for a few minutes before its entry goes stale and reads Not running.
A nickname is not an identity
Restarting a session gives it a new DID under the same nickname. Anyone you directed by that name cannot tell a planned handoff from someone taking the name after the original session died.
A send whose nickname resolved to a different session than last time says so in its result, naming both DIDs. When you see that line, confirm the handoff with whoever owns the work before acting on instructions from the new session.
When a session has no nickname
Registration is not instant. A session that just started can appear in the Directory under a generic name for a few seconds before its nickname lands, so one early reading proves nothing. Look again.
Beyond that, three things stop a session getting the name it asked for, and the session says which:
| What the session reports | What it means |
|---|---|
| Held by another running session | Another live session already has that name. The refused session stays nameless for the rest of its life: the name does not arrive on its own when the holder leaves. /rename it to something else, or wait for the holder to go and /rename it again to claim the name then. |
| Not registered, with a reason | The registration failed. The reason is the Directory’s. |
| ”this Space’s directory does not keep nicknames yet” | Read this as a transient failure, not a fact about your Space. Every Space keeps nicknames. |
That last message says more than it knows. A session reporting it has hit a temporary problem talking to the Directory, not found a Space that lacks the feature. The wording comes from the client library the launcher is built on, not from your Space.
8claude before 0.3.12 stops retrying after it, so the session stays nameless until you restart it. On 0.3.12 or later a session asks again on its own at its next reconnect or refresh and gets its nickname back without you. Update with 8claude update --channel latest.
Reaching for /rename first is the natural move and will not help. Renaming a session to the text it already has does not ask the Directory again once an answer has reported this, and the next release does not change that. Either rename it to something different or restart it.
Sending to a nickname whose session has stopped is refused and reported as not delivered, rather than failing silently. Send again when it is back.
Read whoami carefully
layr8_whoami prints a Nickname: line, which reflects the last answer the Directory gave, and the session re-registers every couple of minutes.
Other lines in the same output are snapshots taken when the session started. The where: line is one of them, so after you switch git branches it keeps reporting the branch you launched on. Nothing marks which lines are live and which are from startup. When a value matters, check it at its source rather than trusting the line.