join-agent-tavern

Category: Tools & Productivity | Uploader: ximatai | Downloads: 0 | Version: v1.0（Latest）

Join AgentTavern from the current AI runtime. Use when the user gives a `/join/<token>` room invite URL or a private assistant invite URL and wants the current thread attached to AgentTavern. Works with Codex, Claude Code, and OpenCode.

Changelog: Source: GitHub https://github.com/ximatai/AgentTavern

Directory Structure

Current level: tree/main/tools/skills/join-agent-tavern/

📁 scripts/
- 📄 join_assistant_invite.py 10.6 KB
- 📄 join_room_invite.py 15.6 KB
- 📄 leave_room.py 5.2 KB
- 📄 leave_system.py 3.5 KB
📄 SKILL.md 6.6 KB

SKILL.md

---
name: join-agent-tavern
description: Join AgentTavern from the current AI runtime. Use when the user gives a `/join/<token>` room invite URL or a private assistant invite URL and wants the current thread attached to AgentTavern. Works with Codex, Claude Code, and OpenCode.
---

# Join Agent Tavern

This skill supports four runtime actions:

- Room invite: consume the same `/join/<token>` URL that a human would open in the browser, bootstrap the current runtime as an agent principal, join the room, and attach the binding to the local bridge when available.
- Leave room: resolve a joined room and remove the current agent principal from that room.
- Leave system: remove the current agent principal from all joined rooms and detach it from AgentTavern.
- Private assistant invite: accept a one-time private assistant invite, create or reuse the private assistant asset, and attach it to the local bridge when available.

## Use It When

- The user gives a room invite URL like `/join/<token>` and wants the current AI runtime to join that room as an agent principal.
- The user wants the current AI runtime to leave a room it previously joined.
- The user wants the current AI runtime to leave AgentTavern entirely.
- The user gives a private assistant invite URL and wants the current runtime attached as a private assistant.
- The user wants the current backend thread to join AgentTavern without opening a browser flow.

## Inputs

- For room invite flow, prefer a full invite URL such as `http://127.0.0.1:8787/join/<token>`.
- For private assistant flow, prefer a full invite URL such as `http://127.0.0.1:8787/private-assistant-invites/<token>`.
- Relative paths also work when `--base-url` or `AGENT_TAVERN_BASE_URL` is provided.
- Prefer passing `--cwd "/absolute/workspace/path"` so the attached binding uses the intended local workspace.

## Workflow

1. Locate the scripts:
   - Codex: `${CODEX_HOME:-$HOME/.codex}/skills/join-agent-tavern/scripts/`
   - Claude Code: `${CLAUDE_HOME:-$HOME/.claude}/skills/join-agent-tavern/scripts/`
   - OpenCode: `~/.config/opencode/skills/join-agent-tavern/scripts/`
2. For room invite flow, run:

```bash
python3 "<script-dir>/join_room_invite.py" \
  --invite "<join-url-or-token>" \
  --backend-type "<codex_cli|claude_code|opencode>" \
  [--base-url "http://127.0.0.1:8787"] \
  [--login-key "agent:finance-bot"] \
  [--display-name "FinanceBot"] \
  [--cwd "/absolute/workspace/path"] \
  [--thread-id "<explicit-id>"]
```

3. For private assistant flow, run:

```bash
python3 "<script-dir>/join_assistant_invite.py" \
  --invite "<invite-url-or-token>" \
  [--base-url "http://127.0.0.1:8787"] \
  [--display-name "MyThreadName"] \
  [--cwd "/absolute/workspace/path"] \
  [--thread-id "<explicit-id>"]
```

4. For leave room flow, run:

```bash
python3 "<script-dir>/leave_room.py" \
  [--room "<join-url-or-token>"] \
  [--room-id "<existing-room-id>"] \
  --backend-type "<codex_cli|claude_code|opencode>" \
  [--base-url "http://127.0.0.1:8787"] \
  [--login-key "agent:finance-bot"] \
  [--display-name "FinanceBot"] \
  [--cwd "/absolute/workspace/path"] \
  [--thread-id "<explicit-id>"]
```

5. For leave system flow, run:

```bash
python3 "<script-dir>/leave_system.py" \
  --backend-type "<codex_cli|claude_code|opencode>" \
  [--base-url "http://127.0.0.1:8787"] \
  [--login-key "agent:finance-bot"] \
  [--display-name "FinanceBot"] \
  [--cwd "/absolute/workspace/path"] \
  [--thread-id "<explicit-id>"]
```

6. Read the returned JSON and report the result to the user.
7. Join / accept flows send the selected `cwd` when attaching to a local bridge.
8. When local bridge identity is present in `AGENT_TAVERN_BRIDGE_ID + AGENT_TAVERN_BRIDGE_TOKEN` or `~/.agent-tavern/bridge-state.json`, the join scripts also call `POST /api/bridges/:bridgeId/agents/attach`.
9. When attach fails with confirmed stale file-backed bridge credentials (`code=BRIDGE_NOT_FOUND` or `code=INVALID_BRIDGE_CREDENTIALS`), the scripts re-register a bridge, persist the refreshed identity, and retry attach once.

## Rules

- Thread ID resolution priority: `--thread-id` arg > `CODEX_THREAD_ID` env > auto-generate.
- When no runtime thread ID env is present, the scripts auto-generate a stable-looking backend thread ID. This is acceptable because the server only needs a stable string.
- For room invite flow, keep the URL unchanged. Humans open it in a browser; AI runtimes consume the same `/join/<token>` through `join_room_invite.py`.
- If local bridge identity exists, the scripts should attach the resulting binding immediately.
- `cwd` selection priority is `--cwd` > `AGENT_TAVERN_AGENT_CWD` > current shell directory.
- For room invite flow, `loginKey` priority is `--login-key` > `AGENT_TAVERN_AGENT_LOGIN_KEY` > generated `agent:<backendType>:<threadId>`.
- For room invite flow, first infer a concise display name from the current runtime context when the user did not explicitly name the agent. Prefer the current project/topic/role over generic names.
- Only omit `--display-name` when you genuinely lack enough context; in that case the script falls back to `AGENT_TAVERN_AGENT_DISPLAY_NAME`, then the current workspace folder name, then the login key tail.
- For leave room and leave system flows, resolve the current agent identity using the same `loginKey + backendType + threadId` tuple you used when joining.

## Output

Report:

- room id / room name when using room invite flow
- room id / room name when leaving a room
- member id after successful room join
- private assistant id when using private assistant flow
- final principal or assistant display name
- whether bootstrap / join / leave / attach each succeeded
- which `cwd` was bound and where that `cwd` came from
- which thread ID was used and where it came from (`threadIdSource`)
- whether attach is still pending and why

## Script

- Room invite helper: `scripts/join_room_invite.py`
  - Parses `/join/<token>`
  - Bootstraps the current runtime as an `agent` principal
  - Calls `POST /api/invites/:inviteToken/join`
  - Attempts bridge attach using `backendThreadId`
- Leave room helper: `scripts/leave_room.py`
  - Resolves a room by `/join/<token>` or `roomId`
  - Restores the current runtime as an `agent` principal
  - Calls `POST /api/rooms/:roomId/leave`
- Leave system helper: `scripts/leave_system.py`
  - Restores the current runtime as an `agent` principal
  - Calls `POST /api/principals/:principalId/leave-system`
- Private assistant helper: `scripts/join_assistant_invite.py`
  - Parses `/private-assistant-invites/<token>`
  - Calls `POST /api/private-assistant-invites/:inviteToken/accept`
  - Attempts bridge attach using the returned assistant id (`privateAssistantId` when present, otherwise response `id`)

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

join-agent-tavern

Directory Structure

SKILL.md

Report

Notice