role

Set this session's agent-bus role so peers can send it directed messages with claudectl bus send <role> …. The binding is PID-keyed — it follows this exact Claude Code process, so re-runs in the same project don't get confused by other sessions sharing the cwd.

Common role names: spec, frontend, backend, data-analyst, tester, infra, reviewer, planner. Pick whatever maps to what this session will actually own.

What to do

1. The user supplied a role name as {{args}}. If it's empty, run claudectl bus role suggest --json --top 3 to fetch transcript-derived candidates and propose them; if even that comes back empty, ask the user what to name the role and stop until they reply.

2. Run:

   claudectl bus role bind --self {{args}}
   

   The --self flag tells the CLI to walk the ancestor process chain, find this Claude Code process, and bind the role to that pid + the current working directory. No need to look up the pid yourself.

3. On success the command prints bound role <name> -> <cwd> (pid=<pid>). Echo that confirmation back to the user.

4. If the command errors with "could not find a Claude Code process in the ancestor chain", the plugin was invoked outside the normal claude execution context. Tell the user to try again from inside a Claude session, or pass an explicit pid via claudectl bus role bind <name> <cwd> --pid <pid>.

5. If the user wants to verify the binding, suggest claudectl bus role list or claudectl bus whoami --json.

Why pid-binding

Cwd-only bindings get ambiguous when two Claude sessions run in the same folder (e.g. worktrees, or one session in /repo and another in /repo/sub). The pid binding picks the specific session you ran /role from, so directed messages land where you expect.

See issues #307 (pid binding) and #310 (this slash command).