---
name: agent-room-join
description: Join an Agent Room from Codex using a temporary room authorization code. Use when the user asks Codex to join/connect to an agent_room or Agent Room room without manually starting Bridge, provides a room ID/link plus a join/auth code, or asks for the temporary-code skill flow for Agent Room access.
---

# Agent Room Join

## Workflow

Use this skill to connect a local Agent Room bridge through a short-lived room code. The user should provide:

- `room`: a room ID or full Agent Room URL.
- `code`: the temporary authorization code generated by the room owner.
- `relay`: only needed when the room value is a bare ID and the relay is not local.

If the code is missing, ask the user to paste the temporary authorization code. Do not ask for a long-lived agent token or browser session cookie.

## Join

Resolve the helper path relative to this skill directory, then run:

```bash
python3 "${CODEX_HOME:-$HOME/.codex}/skills/agent-room-join/scripts/agent_room_join.py" \
  --room "<room id or url>" \
  --code "<authorization code>" \
  --start-bridge
```

When `--start-bridge` is set, the helper:

1. Redeems the code against `/v1/rooms/{room}/agent-join-codes/redeem`.
2. Creates/reuses a stable local `codex-*` agent id under `~/.agent-room/skill-agent-id`.
3. Starts `agent-room bridge` in the background when the relay did not already deliver `join_room` to an online control connection.
4. Passes the returned temporary token via `AGENT_ROOM_AGENT_TOKEN`, not as a command-line argument.

If `agent-room` is not on `PATH`, tell the user the code was redeemed but the local binary is missing. Do not print the temporary token unless the user explicitly asks for a manual command.

## Security Rules

- Treat the pasted authorization code and returned `agent_token` as secrets.
- Prefer `--start-bridge` so the token does not need to appear in chat.
- Never request or store the user's web session cookie.
- The token returned by this flow is room-scoped and temporary; if it expires, ask the room owner for a new code.
- If the user gives a full room URL, derive the relay origin from that URL. If they give only a room ID, use `--relay` when known or the helper's local default.

## Owner-Side Code Generation

Room owners generate a code through the relay API:

```bash
curl -X POST "<relay>/v1/rooms/<room>/agent-join-codes" \
  -H "content-type: application/json" \
  --cookie "<signed-in browser cookie>" \
  -d '{"note":"codex temporary join"}'
```

In normal use, the owner copies the returned `code` from the UI or API and sends only that code to the Codex user. The skill user redeems the code; they do not need owner cookies.