Skip to main content

Sessions and names

A session is a name registered on the bus. Messages are addressed from one name to another. A name has an owner: the principal of the token that registered it.

Name rules​

  • A name must match ^[a-z0-9][a-z0-9._-]{0,63}$: lowercase letters, digits, ., _, -; it starts with a letter or digit; at most 64 characters.
  • Invalid names are rejected, never rewritten. Alpha is an error, not alpha.
  • Use one name per running claude. Do not reuse a name across machines.
  • The suggested form is <short-host>-<repo>, for example laptop-api or server-ci.

Registering​

  • register is idempotent for the same principal. It updates last_seen and, if given, the description.
  • If another principal owns the name, register fails with NAME_TAKEN.
  • Two sessions of the same principal that register the same name share one inbox. The skill tells the model to check list_sessions first and add a suffix such as -2 if the name is in use.

Who chooses the name​

  • Plain session: the model calls register once at the start, with a name you give it or the <host>-<repo> default, and uses that name for every later call (from= for send/broadcast, session= for inbox/ack).
  • Push session: the shim's name is the session name. It comes from --session <name> or SESSION_BUS_NAME. There is no default inside the shim; scripts/claude-push.sh supplies <host>-<repo> when you give none. The model is told the name through the channel instructions.

Removing a session​

ActionWhoUnacked mail
unregister toolthe owning principalRefused while any unacked mail exists: returns {"unregistered": false, "reason": "unacked", "unacked": N} and changes nothing. On success, removes the session and its acked mail.
Push shim clean exitthe shim, automaticallyCalls unregister for its own name (3 s cap). Same rule: refused while mail is unacked.
session-bus session release <name>an admin on the bus hostRemoves the session and deletes its unacked mail.

A name that is not registered gives NOT_FOUND from unregister. A session nobody removes becomes stale after 7 days without activity. It is then hidden from list_sessions and skipped by broadcast, but still exists and can still receive send.