Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(codex): standalone setup via a configure skill — connect to Switch without switchdash (CHOO-1936) (#129)

Christian McDermott6adb226677aa
diff --git a/.gitignore b/.gitignore
index 5b576661f..4fb674e18 100644
--- a/.gitignore
+++ b/.gitignore
@@ -197,6 +197,7 @@ cython_debug/
# Ignore directories containing user credentials, local state, and settings.
# Learn more at https://abstra.io/docs
.abstra/
+.switch/
# Visual Studio Code
# Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
@@ -236,4 +237,4 @@ related-projects
.switchdash/
.switchdash-icon-drop/
download.txt
-download.xml
\ No newline at end of file
+download.xml
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 263c3194f..410229009 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1248,6 +1248,16 @@ manifest history.
### [Unreleased]
+### [0.3.2] - 2026-08-12
+
+#### Added
+- A `configure` skill: the standalone setup path. Registers this Codex instance
+ as a Switch agent and writes `.switch/agents/<name>.json` in the working
+ directory, so `codex` reaches Switch with no Switch Console involved
+ (CHOO-1936). It writes no MCP config — the plugin's `.mcp.json` stays the
+ single server definition and the runtime resolves its own identity from the
+ store (`switch-agent-runtime` 0.2.0+).
+
### [0.3.1] - 2026-08-12
#### Changed
diff --git a/CLAUDE.md b/CLAUDE.md
index 65e6536bb..3de579d83 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -105,7 +105,10 @@ each ships its own copy of the Switch room-workflow skill at
Switch Console imports the same package for its protocol client, so there is one
implementation of the agent protocol rather than a copy per consumer.
- `connectors/codex-plugin/` — manifest `.codex-plugin/plugin.json`. Ships the
- skill plus its own MCP config, declared as `"mcpServers": "./.mcp.json"`, so a
+ room-workflow skill, a **`configure`** skill (the standalone setup path — it
+ registers the agent and supplies the bundled server's credentials so Codex
+ reaches Switch with no Switch Console involved), and its own MCP config,
+ declared as `"mcpServers": "./.mcp.json"`, so a
Codex session gets the Switch tools from the plugin alone. Codex does not
expand `${VAR}` in a bundled config, so the server names its variables under
`env_vars` and Codex forwards them **by name** from its own environment — no
diff --git a/artifacts.yaml b/artifacts.yaml
index 8d9c6683e..ae4a6a2e6 100644
--- a/artifacts.yaml
+++ b/artifacts.yaml
@@ -132,7 +132,7 @@ artifacts:
switch-connector-codex:
description: The Codex connector plugin.
- version: 0.3.1
+ version: 0.3.2
declared_in: connectors/codex-plugin/.codex-plugin/plugin.json
contracts:
diff --git a/connectors/codex-plugin/.codex-plugin/plugin.json b/connectors/codex-plugin/.codex-plugin/plugin.json
index e178eb36a..0c5530d88 100644
--- a/connectors/codex-plugin/.codex-plugin/plugin.json
+++ b/connectors/codex-plugin/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "switch-connector-codex",
- "version": "0.3.1",
+ "version": "0.3.2",
"description": "Connect Codex to a Switch platform instance as a participating agent",
"skills": "./skills/",
"mcpServers": "./.mcp.json"
diff --git a/connectors/codex-plugin/README.md b/connectors/codex-plugin/README.md
index 9ad5b50e5..eb4f925fc 100644
--- a/connectors/codex-plugin/README.md
+++ b/connectors/codex-plugin/README.md
@@ -1,11 +1,15 @@
# switch-connector (Codex)
-The Codex build of the Switch connector plugin. It ships the **Switch
-room-workflow skill** (`skills/switch/SKILL.md`) — the room workflow,
-interaction modes, thread semantics, task protocol, room roles, and
-moderation tools an agent needs in order to participate in a Switch room
-correctly — and the **Switch MCP server** that provides the tools the skill
-describes.
+The Codex build of the Switch connector plugin. It ships the **Switch MCP
+server** that provides the Switch tools, plus two skills:
+
+- **`skills/switch/SKILL.md`** — the room workflow, interaction modes, thread
+ semantics, task protocol, room roles, and moderation tools an agent needs in
+ order to participate in a Switch room correctly.
+- **`skills/configure/SKILL.md`** — the **standalone setup path**: register
+ this Codex instance as a Switch agent and give the bundled server the
+ credentials it needs, so `codex` connects to Switch with no Switch Console
+ involved. See "Standalone setup" below.
Manifest: `.codex-plugin/plugin.json`. Registered in the repo marketplace
(`.claude-plugin/marketplace.json`) as `switch-connector-codex`.
@@ -114,6 +118,62 @@ the pre-profile design declares a `url`, which merges with a `command` entry
into a server that is both, and Codex then refuses to load the config at all.
Switch Console removes such an entry.
+## Standalone setup (no Switch Console)
+
+The `configure` skill covers the case Switch Console does not: a user who installs
+this plugin and wants `codex` to reach Switch from a plain terminal. It
+registers the agent against the bridge (`POST /agents/register-known` with
+`agent_type: "codex"`) and writes the credentials to
+`.switch/agents/<name>.json` in the working directory.
+
+**It writes no MCP config at all.** The plugin's `.mcp.json` is the single
+server definition; the skill supplies only the *identity*. Since
+`switch-agent-runtime` 0.2.0 the runtime resolves that itself — environment
+first (Switch Console's path, untouched), otherwise the local agent store read from
+the session's working directory.
+
+That division matters, because the obvious alternative is actively harmful.
+Supplying credentials through a second `mcp_servers.switch` entry does not work:
+measured against codex-cli 0.146.0, a config-file entry **replaces** a
+plugin-provided server rather than merging with it per key, dropping
+`default_tools_approval_mode: approve` — which leaves the agent unable to post —
+along with `startup_timeout_sec`. An entry with no transport of its own is
+rejected outright as `invalid transport`, taking every Codex session on the
+machine with it. There is no way to layer credentials onto a plugin-provided
+server, which is precisely why the runtime learned to find them itself.
+
+### What standalone does and does not get
+
+Works: the full Switch tool surface (including `send_attachment` /
+`download_attachment` — neither is gated on which process owns the connection),
+room participation, tasks, roles, moderation, and the offline run command.
+
+Does not: **inbound events are not pushed into the session.** Switch Console reads
+the session's event connection and injects `[Switch] …` lines into its pane;
+standalone, nothing does. The runtime opens its own connection (no
+`SWITCH_CONNECTION_ID` is set, which is correct — that names a connection a
+supervisor has already opened to share), but the session is pull-based: it calls
+`read_context` to catch up rather than being notified. Also absent:
+`auto_session` spawning, and per-agent model / reasoning-effort / instruction
+overrides.
+
+### Identity is per working directory
+
+The store is read from the session's working directory, so a different directory
+with its own `.switch/agents/` is a different agent. Two consequences worth
+knowing:
+
+- `repo_dir` should be the directory the credentials were written into. The
+ offline run command Switch posts is a bare
+ `cd "<repo_dir>" && codex "connect to switch room <name>"`, so if the two
+ disagree the pasted command starts Codex where the store isn't.
+- Several agents in one directory is supported: the runtime leaves the identity
+ open and the session binds one with `select_agent`. Agents spanning **several
+ Switch servers** is not — startup refuses, because the catalog is fetched
+ before the handshake and picking a server arbitrarily would bootstrap a tool
+ surface from a deployment the agent may not belong to. `SWITCH_API_ENDPOINT`
+ disambiguates.
+
## What the registered runtime gives a Codex session
The runtime is the same package the Claude Code connector registers, so a
diff --git a/connectors/codex-plugin/skills/configure/SKILL.md b/connectors/codex-plugin/skills/configure/SKILL.md
new file mode 100644
index 000000000..bc8641f81
--- /dev/null
+++ b/connectors/codex-plugin/skills/configure/SKILL.md
@@ -0,0 +1,455 @@
+---
+name: "configure"
+description: "Set up the Switch connector for Codex — register this Codex instance as a Switch agent and write the credentials the bundled MCP server reads. Use when the user asks to configure Switch, set up the plugin, register with a Switch server, or when the Switch tools report no identity."
+---
+
+# Configure the Switch connector (Codex)
+
+This skill registers the current Codex instance as a Switch agent and writes
+its credentials where the Switch runtime looks for them, so a session started
+from a plain terminal acts as that agent.
+
+**This is the standalone path.** Sessions launched by **Switch Console** need none
+of it — Switch Console registers each agent and injects its identity per session.
+Run this skill when there is no Switch Console: install the plugin, run this once
+in the directory you work from, and `codex` connects to Switch on its own.
+Read "What you get without Switch Console" before promising a capability, because
+the standalone path is deliberately not feature-complete.
+
+## What this skill does and does not touch
+
+The plugin already ships the MCP server: `.mcp.json` declares `mcp_servers.switch`
+with the runtime, its version pin, `startup_timeout_sec`, and
+`default_tools_approval_mode: "approve"`. **Leave that alone.**
+
+> ⚠️ **Never write an `mcp_servers.switch` entry anywhere.** Not in
+> `$CODEX_HOME/config.toml`, not in a profile, not via `codex mcp add`, not with
+> `-c` on argv. Measured against codex-cli 0.146.0, a config-file entry does not
+> merge with a plugin-provided server per key — it **replaces** it, silently
+> dropping `default_tools_approval_mode: approve` and `startup_timeout_sec`.
+> Losing `approve` means write-annotated tools are refused, so the agent can no
+> longer post; and an entry with no transport of its own is rejected outright
+> with `invalid transport`, which kills **every** Codex session on the machine.
+> The plugin's config is the single definition. This skill supplies only the
+> *identity*.
+
+The runtime resolves its own identity, in this order:
+
+1. **`SWITCH_API_ENDPOINT` / `SWITCH_API_TOKEN` / `SWITCH_AGENT_ID` in the
+ environment**, if all three are set — Switch Console's path.
+2. **Otherwise the local agent store**, `.switch/agents/*.json`, read from the
+ **session's working directory**. That is what this skill writes.
+
+Half an environment (one or two of the three) is a hard error, not a fallback —
+authenticating as the wrong agent is worse than not starting.
+
+**Requires `switch-agent-runtime` 0.2.0 or newer.** Earlier runtimes read only
+the environment and will report no identity no matter what this skill writes.
+The version in play is the pin in the plugin's `.mcp.json`; if it is below
+0.2.0, the plugin needs upgrading first and this skill cannot help until then.
+
+## Step 1 — Check what is already there
+
+The store is read from the **working directory**, so check the directory the
+user will start Codex in:
+
+```bash
+ls .switch/agents/*.json 2>/dev/null
+```
+
+- **Nothing** — continue to Step 2.
+- **One entry** — this directory already has an identity. Report the agent name
+ and server, and ask whether to keep it. **Default to keeping it**:
+ re-registering mints a fresh agent and orphans the old one in Switch, along
+ with its rooms, history and task ledger. Adding a *second* agent here is a
+ legitimate separate answer — see the note on `select_agent` below.
+- **Several entries** — the runtime cannot pick between them on its own. That is
+ supported: it leaves the identity open and the session binds one with
+ `select_agent`. Only add another if the user actually wants a choice at
+ session start.
+
+**Also check the environment, because it silently wins.** The runtime takes a
+complete `SWITCH_*` environment ahead of the store, so a shell that already
+exports one makes everything this skill writes inert — the session runs as
+whatever that environment names, with no warning:
+
+```bash
+for v in SWITCH_API_ENDPOINT SWITCH_API_TOKEN SWITCH_AGENT_ID; do
+ eval "printf '%s=%s\n' \"$v\" \"\${$v:+set}\""
+done
+```
+
+(One lookup per variable, deliberately. `printenv A B C` is not portable for
+this: BSD/macOS `printenv` only reports on the **first** name, so a partial
+leak — say `SWITCH_AGENT_ID` alone — prints nothing and reads as a clean
+environment. A partial environment is exactly the case the runtime treats as a
+hard error, so a false "clean" here is the worst possible answer.)
+
+If all three are set, tell the user before going further: either they are
+already configured and don't need this skill, or those variables are leaking in
+from somewhere (a Switch Console-spawned terminal exports them) and Codex must be
+started from a shell without them for the store to be used at all.
+
+If entries exist for **different Switch servers**, say so plainly: the runtime
+**refuses to start** in that case, because the operation catalog is fetched
+before the handshake and picking a server arbitrarily would bootstrap a tool
+surface from a deployment the agent may not belong to. The fix is either to set
+`SWITCH_API_ENDPOINT` to the intended server, or to keep only one server's
+agents in the directory.
+
+## Step 2 — Switch server URL, and prove it before going on
+
+You need the **agent-bridge** URL, which on most deployments is **not** the
+gateway URL. The gateway is the web UI where the user mints their token; the
+bridge is the API the runtime talks to. They are usually different hosts — e.g.
+`switch-gateway.example.ts.net` (UI) versus `switch-api.example.ts.net`
+(bridge) — and a user who has only ever visited the UI will naturally hand you
+that one.
+
+If `SWITCH_API_ENDPOINT` is set in the environment, offer it. Otherwise ask,
+and say explicitly that you want the **API/bridge** URL, not the gateway UI
+address — for a local dev stack that is `http://localhost:8000`, with the
+gateway on `:3000`.
+
+**It must be a bare base URL** — scheme and host, no path. Users paste what is
+in their browser, which usually has one (`…/registration-keys` is the token
+page, not the API root). Strip any path and trailing slash before using it.
+
+**Then prove it before doing anything else**, with the bridge's public health
+route:
+
+```bash
+curl -s --max-time 10 "$ENDPOINT/health"
+```
+
+- **`{"status":"ok"}`** — correct base URL. Continue.
+- **`401`** — right host, **wrong path**: you have left a path on the end (the
+ bridge authenticates everything except a few public routes, so a bad path
+ answers 401 rather than 404). Strip back to scheme+host and probe again.
+- **`405`, `404`, or HTML** — wrong host. This is the gateway or a static
+ server, not the bridge. Ask for the bridge URL; do not go hunting for another
+ path on this one. `/gateway/agents/register-known` is **not** it — the
+ gateway's registration route is session-authenticated and will not accept a
+ registration token.
+- **Connection refused / DNS failure** — unreachable from here; surface the
+ curl error and stop.
+
+Use `/health` specifically, not the registration route. An unauthenticated POST
+to `/agents/register-known` returns 401 on the correct host *and* on a wrong
+path on that host, so it cannot tell you the base URL is right — measured on a
+live deployment.
+
+Getting this wrong is the single most likely way this skill wastes someone's
+time, because without the probe the mistake only surfaces at registration,
+several steps later, after the user has already handed over a token.
+
+## Step 3 — Registration token
+
+Registration is gated by a token the user mints in the Switch gateway UI under
+the **API keys** tab (a server-side `api_key` of type `"registration"`; the
+bridge resolves it to the owning user, so the new agent is owned by whoever
+issued it).
+
+Check the environment for `SWITCH_REGISTRATION_TOKEN` (`printenv
+SWITCH_REGISTRATION_TOKEN`). If unset, ask the user to paste it and tell them
+exactly where to get it: **"Open the Switch gateway UI for your deployment, go
+to the API keys tab, and create (or copy an existing) registration token."**
+Don't just say "from the admin" — point at the concrete UI surface.
+
+**Treat the token as sensitive.** It mints agents owned by its user. Never echo
+it, never write it to any file.
+
+> ⚠️ **If the user pastes the token into the conversation, it is already
+> exposed** — it is in the transcript, and anything you do next cannot unspill
+> it. Do not compound it by putting the value on a command line, where it also
+> lands in shell history and process listings. Instead:
+>
+> - Ask the user to export it in their own shell and re-run, so it reaches you
+> only as `$SWITCH_REGISTRATION_TOKEN`:
+> `export SWITCH_REGISTRATION_TOKEN=...` (a leading space keeps it out of
+> history in most shells).
+> - If they would rather continue with the pasted value, say plainly that you
+> are going to use it and that **they should rotate it afterwards** in the
+> gateway's API keys tab. Then write it into the environment of the single
+> registration command rather than `export`ing it into the session.
+>
+> Either way, tell them once. A token pasted into a chat window and then used
+> without comment is the failure nobody notices until it matters.
+
+## Step 4 — Agent name and description
+
+Switch validates the name against `^[a-z0-9][a-z0-9._-]*$` — lowercase letters,
+digits, dots, hyphens, underscores; must start with a letter or digit. **No
+spaces, no `@`, no uppercase.** The name is used in Matrix room handles and
+`@mention` syntax.
+
+Suggest a default that **identifies the user**, not just the repo. Agent names
+are visible to everyone in the rooms the agent joins. If two developers both
+register from a shared repo, a repo-only name like `codex.my-project` collides
+and nobody can tell which human is behind which agent:
+
+- `codex.<slug-of-repo-name>.<slug-of-username>` — repo name from
+ `basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"`, username
+ from `$USER` or `whoami`.
+
+To slugify: lowercase, replace anything outside `[a-z0-9._-]` with `-`, collapse
+repeats, strip leading/trailing `-`.
+
+Confirm the name or accept a custom one; if it fails the regex, explain why and
+ask again. If it carries no user identifier, flag the collision risk once and
+let the user decide.
+
+Also ask for a one-line description — it appears in room participant lists.
+Default: `Codex running in <repo-name-or-hostname>`.
+
+> **No channels question, and no subagents step.** The Claude Code connector has
+> both; Codex has neither. `CodexOptions` has no `channels_enabled` field —
+> sending one is silently dropped — and Codex has no `.claude/agents/*.md`
+> equivalent, so the bulk endpoint would mint indistinguishable children. Do not
+> call it.
+
+## Step 5 — Repository directory and notify user
+
+Switch shows room participants a paste-ready command when the agent is
+addressed with no live session:
+
+```
+cd "<repo_dir>" && codex "connect to switch room <name>"
+```
+
+`repo_dir` is what makes it useful — **and for Codex it matters twice over**,
+because the runtime reads the agent store from the session's working directory.
+`repo_dir` should therefore be **the directory this skill writes the credentials
+into**, or the pasted command starts Codex somewhere the store isn't and the
+session has no identity.
+
+Ask whether to record it, defaulting to the current working directory. Validate
+that it is absolute (`startswith("/")`) and exists (`test -d`).
+
+Then ask whether to record `notify_user` — a handle to `@`-mention on the
+bridged platform so the operator gets a push notification. Explain: *"Use the
+exact handle they have on the room's bridged platform (Slack / Mattermost), or
+their Switch user name for unbridged rooms — often NOT the local username. If it
+doesn't match a real bridge user the mention silently does nothing."* Ask for
+the bare handle, no leading `@`, and do not default to `$USER`.
+
+Omit either key entirely if the user opts out — leave it out rather than passing
+an empty string, so the schema default applies.
+
+**Do not set `auto_session`.** It means "Switch Console watches rooms and auto-spawns
+a session"; with no Switch Console there is nothing to do the spawning, so setting it
+advertises a capability that does not exist.
+
+## Step 6 — Register
+
+`POST /agents/register-known` with the registration token in the header. It
+looks up the `codex` known-agent spec and returns the agent's `id` and
+`api_key`. Do not inline the token — command lines reach shell history and
+process listings:
+
+```bash
+curl -sf -X POST "$ENDPOINT/agents/register-known" \
+ -H "Authorization: Bearer $SWITCH_REGISTRATION_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d "$(jq -nc --arg name "$NAME" --arg desc "$DESC" \
+ --arg repo_dir "$REPO_DIR" --arg notify_user "$NOTIFY_USER" \
+ '{agent_type:"codex", name:$name, description:$desc,
+ options:((if $repo_dir == "" then {} else {repo_dir:$repo_dir} end)
+ + (if $notify_user == "" then {} else {notify_user:$notify_user} end)),
+ overwrite:false}')"
+```
+
+**Pitfall — env-var expansion order.** Do NOT prefix the command with
+`SWITCH_REGISTRATION_TOKEN=... curl ...` while also referencing
+`$SWITCH_REGISTRATION_TOKEN` in it. The shell expands the variable against the
+*parent* environment *before* the inline assignment applies, so you send
+`Authorization: Bearer ` (empty), curl drops the header, and the bridge answers
+`401 Missing or invalid Authorization header` — which looks like a bad token but
+isn't. `export` it first, or assign to a shell variable on a preceding line. If
+you see that exact 401, suspect this before blaming the token.
+
+The response is `{"id":"...","api_key":"..."}`. If `curl` exits non-zero, re-run
+with `-i` instead of `-sf` and show the user the status and body, then stop.
+
+> ⚠️ **Register and write the credentials file in ONE shell command.** This is
+> the single most important instruction in this skill, and getting it wrong is
+> the one way to leave things worse than you found them.
+>
+> The `api_key` is returned by that one call and **never again** — it cannot be
+> read back from the server. And **each command you run is a separate shell
+> process**, so a variable set in one does not exist in the next. Register in
+> one command and try to use `$api_key` in another and it is empty: the agent
+> now exists on the server with a token nobody holds, and re-registering to
+> recover returns `409`.
+>
+> This is not hypothetical — it happened twice in testing before this note
+> existed. So do not split them. Do the curl and the file write in a **single**
+> invocation, as Step 7 shows, or at minimum redirect the response body to a
+> file (`--output`) in the same command that makes the request, and read it
+> back from there.
+>
+> Two shell details, both from real runs: `status` is a **reserved variable in
+> zsh** — use `http_status` — and a `$(...)` capture of the body must not
+> swallow the exit code you intend to branch on.
+
+**Responses:**
+
+- `401` — bad registration token (or the pitfall above); stop.
+- `400 Unknown agent type: codex` — the server predates Codex support. Say so
+ and stop; do not fall back to another type.
+- `400` with a name validation error — re-ask in Step 4.
+- `409` — that name already exists. The bridge refuses to clobber it because
+ re-registering rotates the API key and invalidates the old credentials.
+ **First work out which case this is**, because the fix differs:
+ - **You created it moments ago, in this run** (a retry, or a re-run after a
+ later step failed). The agent is yours but its token is gone — it was only
+ ever returned once. There is no way to read it back, so the only recoveries
+ are to re-run with `overwrite:true` (mints a fresh key for the same name)
+ or to pick a new name and leave the orphan behind. Say plainly which you
+ are doing and why; do not present this as a clean success.
+ - **It pre-dates this run** — someone else's agent, or the user's own from an
+ earlier setup. Ask before touching it; the recommended answer is a
+ different name. Overwriting rotates a key that a live session may be using.
+
+ Only use `overwrite:true` on an explicit decision. Never silently.
+- Any other non-2xx — show status and body, then stop.
+
+## Step 7 — Write the credentials file
+
+**Do this in the same command as Step 6's registration** — see the warning
+there.
+
+> ⚠️ **Write these lines to a file and run that file.** Do not paste them
+> inside `bash -lc '...'`. The jq filter is single-quoted, and nesting it in an
+> outer single-quoted string collapses the quoting — jq then sees bare
+> `agent_type:"codex"` and dies with `syntax error, unexpected ':'`, or curl
+> receives a blank argument. This has already cost one real run:
+>
+> ```bash
+> cat > /tmp/switch-configure.sh <<'SCRIPT'
+> ...the script below...
+> SCRIPT
+> bash /tmp/switch-configure.sh
+> ```
+>
+> The quoted heredoc (`<<'SCRIPT'`) is what keeps the body intact.
+
+`ENDPOINT`, `NAME`, `DESC`, `REPO_DIR`, `NOTIFY_USER` and
+`SWITCH_REGISTRATION_TOKEN` must be exported in the environment the script runs
+in. `REPO_DIR` and `NOTIFY_USER` may be empty strings — the server normalises a
+blank to "unset", so there is no need to build the payload conditionally.
+
+```bash
+set -eu
+mkdir -p .switch/agents
+printf '*\n' > .switch/agents/.gitignore
+
+resp=$(mktemp)
+http_status=$(curl -s -o "$resp" -w '%{http_code}' -X POST "$ENDPOINT/agents/register-known" \
+ -H "Authorization: Bearer $SWITCH_REGISTRATION_TOKEN" \
+ -H 'Content-Type: application/json' \
+ -d "$(jq -nc --arg name "$NAME" --arg desc "$DESC" \
+ --arg repo_dir "$REPO_DIR" --arg notify_user "$NOTIFY_USER" \
+ '{agent_type:"codex", name:$name, description:$desc,
+ options:{repo_dir:$repo_dir, notify_user:$notify_user},
+ overwrite:false}')")
+
+if [ "$http_status" != "200" ]; then
+ printf 'registration failed (%s): ' "$http_status"; cat "$resp"; echo; rm -f "$resp"; exit 1
+fi
+
+jq --arg ep "$ENDPOINT" \
+ '{env: {SWITCH_API_ENDPOINT: $ep, SWITCH_API_TOKEN: .api_key, SWITCH_AGENT_ID: .id}}' \
+ "$resp" > ".switch/agents/$NAME.json"
+chmod 600 ".switch/agents/$NAME.json"
+jq -r '"registered " + .id' "$resp"
+rm -f "$resp"
+```
+
+The token goes from the response straight into the file without ever being
+echoed or held in a variable that a later command would need. The resulting
+file is the same shape Switch Console writes:
+
+```json
+{
+ "env": {
+ "SWITCH_API_ENDPOINT": "<url from step 2>",
+ "SWITCH_API_TOKEN": "<api_key>",
+ "SWITCH_AGENT_ID": "<id>"
+ }
+}
+```
+
+Write it in the directory the user will start Codex from — the same one used for
+`repo_dir` in Step 5. The runtime reads the store from the session's working
+directory, so a file in the wrong directory is simply not found.
+
+Add `.switch/` to the repo's own `.gitignore` too if it is not already covered.
+The token lives in this file in plaintext, inside the working tree; say so
+plainly rather than leaving the user to find it.
+
+No MCP config is touched. The plugin's `.mcp.json` already declares the server,
+and the runtime reads this file itself.
+
+## Step 8 — Confirm
+
+Report to the user:
+
+- The agent name and ID registered with Switch.
+- That credentials went to `.switch/agents/<name>.json` (git-ignored), and that
+ the **token is stored there in plaintext** inside the working tree — a
+ credential at rest in a directory they may archive or copy.
+- That Codex must be **restarted** to pick up the identity, and that it must be
+ started **from this directory**.
+- How to check: start `codex` here and ask it to `list_rooms`.
+
+Do **not** print the API token. Echoing secrets into a transcript is a common
+way they leak into logs and screenshots.
+
+## What you get without Switch Console
+
+Be straight with the user; do not imply parity.
+
+**Works:** the full Switch tool surface (including `send_attachment` /
+`download_attachment`), room participation, threads, tasks, roles, moderation,
+and the offline run command Switch posts — which is a bare
+`cd "<repo_dir>" && codex "connect to switch room <name>"`, so it works as
+written provided `repo_dir` is where the store lives.
+
+**Does not work, or works differently:**
+
+- **Inbound events are not pushed into the session.** Switch Console reads the
+ session's event connection and injects `[Switch] …` lines into its pane;
+ nothing does that here. Treat the session as pull-based — call `read_context`
+ to catch up rather than waiting to be notified. Do not promise the user that
+ the agent will respond the moment it is addressed.
+- **No auto-spawned sessions.** `auto_session` depends on Switch Console watching
+ rooms; the user starts Codex themselves.
+- **No per-agent model / reasoning-effort / instruction overrides.** Those live
+ in the profile Switch Console writes.
+
+**Identity is per working directory**, not per machine: a different directory
+with its own `.switch/agents/` is a different agent, and several entries in one
+directory are chosen between at session start with `select_agent`.
+
+## Troubleshooting
+
+- **"no Switch identity" / tools present but unusable** — the runtime found no
+ environment and no usable store entry. Check you started Codex from the
+ directory holding `.switch/agents/`, and that the entry parses as JSON with an
+ endpoint, token and agent id.
+- **Startup refuses, naming several servers** — the store spans more than one
+ Switch deployment. Set `SWITCH_API_ENDPOINT` to the one you meant, or keep
+ only that server's agents in the directory.
+- **Tools refuse and name a list of agents** — several agents on one server and
+ no identity bound yet. Call `select_agent` with one of the names first.
+- **Tools missing entirely** — the plugin is not installed or not enabled
+ (`codex plugin list`), or its pinned runtime predates 0.2.0. Restart Codex
+ after any change.
+- **`connection closed: initialize response`** — the runtime died before the
+ handshake; the reason is in `~/.switch/sessions/<ppid>/startup-error.log`. Read
+ it rather than guessing: the host reports every cause identically.
+- **404 fetching the runtime** — the runtime is on the public npm registry, so
+ this is a reachability problem (offline, proxy, or a registry override in an
+ `.npmrc`), not an authentication one. `npm view @sandboxaq/switch-agent-runtime
+ version` should print a version.
diff --git a/console/AGENTS.md b/console/AGENTS.md
index a8cf74ad6..2eb989812 100644
--- a/console/AGENTS.md
+++ b/console/AGENTS.md
@@ -459,7 +459,7 @@ forgotten and someone will debug a build they think is newer than it is.
|---|---|---|
| Remote sidecar | `src/sidecar/sidecar-version.ts` | any behaviour change; **major only** on a client↔sidecar wire break (ready line, endpoint shapes, shared on-disk layout) |
| Claude Code plugin | `connectors/claude-code-plugin/.claude-plugin/plugin.json` | any change to the plugin — installs will not pick it up otherwise |
-| Codex plugin | `connectors/codex-plugin/.codex-plugin/plugin.json` | any change to the plugin (it ships the skill and its own `.mcp.json`) — installs will not pick it up otherwise |
+| Codex plugin | `connectors/codex-plugin/.codex-plugin/plugin.json` | any change to the plugin (the room-workflow and `configure` skills, and its own `.mcp.json`) — installs will not pick it up otherwise |
| Agent runtime package | `packages/switch-agent-runtime/package.json` | any change; it is published, and **both** connectors' `.mcp.json` pin the version sessions actually run. Nothing in the app pins it — the plugins register the runtime themselves — so those two files are the only pins |
"Non-trivial" means anything a user could observe: behaviour, protocol, wiring,
diff --git a/console/packages/shared/src/artifacts.ts b/console/packages/shared/src/artifacts.ts
index 0dcc17df8..c967e75c6 100644
--- a/console/packages/shared/src/artifacts.ts
+++ b/console/packages/shared/src/artifacts.ts
@@ -29,7 +29,7 @@ export const ARTIFACT_VERSIONS = {
'helm-chart': '0.13.2',
compose: '0.13.2',
'switch-connector': '0.9.1',
- 'switch-connector-codex': '0.3.1',
+ 'switch-connector-codex': '0.3.2',
} as const satisfies Record<string, string>;
export type ArtifactName = keyof typeof ARTIFACT_VERSIONS;
diff --git a/console/packages/switch-agent-runtime/src/artifacts.ts b/console/packages/switch-agent-runtime/src/artifacts.ts
index 0dcc17df8..c967e75c6 100644
--- a/console/packages/switch-agent-runtime/src/artifacts.ts
+++ b/console/packages/switch-agent-runtime/src/artifacts.ts
@@ -29,7 +29,7 @@ export const ARTIFACT_VERSIONS = {
'helm-chart': '0.13.2',
compose: '0.13.2',
'switch-connector': '0.9.1',
- 'switch-connector-codex': '0.3.1',
+ 'switch-connector-codex': '0.3.2',
} as const satisfies Record<string, string>;
export type ArtifactName = keyof typeof ARTIFACT_VERSIONS;
diff --git a/core/switch_core/artifacts.py b/core/switch_core/artifacts.py
index ce511fb43..c27c322cb 100644
--- a/core/switch_core/artifacts.py
+++ b/core/switch_core/artifacts.py
@@ -29,7 +29,7 @@ ARTIFACT_VERSIONS: Final[dict[str, str]] = {
"helm-chart": "0.13.2",
"compose": "0.13.2",
"switch-connector": "0.9.1",
- "switch-connector-codex": "0.3.1",
+ "switch-connector-codex": "0.3.2",
}
CONTRACTS: Final[dict[str, dict[str, ContractRange]]] = {