---
name: hermios-connect
description: Use when the user wants to connect Codex to Hermios CRM, sign in, switch or add a Hermios workspace, use another account, or fix a Hermios MCP connection that returns auth errors, 404s, Cloudflare login pages, or missing tools.
---

# When To Use

- "connect Codex to Hermios" / "set up Hermios"
- "sign in to Hermios" / "Hermios says auth required"
- "connect my second Hermios workspace"
- "switch workspace" / "use another account" / "sign out of Hermios"
- An explicit account-action request sent from the native Hermios account menu
- "Hermios tools aren't showing up"

Do not use this skill to read or change CRM data. Use `$hermios-crm` for that once connected.

# Steps

1. Read `../../references/setup.md`.
   - To switch workspace, call `list_hermios_workspaces({})` first. If the target is listed, call `switch_hermios_workspace({ workspaceId })` and report the new workspace. No browser sign-in is needed.
   - For an account-menu action, or a workspace that is not listed yet, follow **Switch Account, Switch Workspace, Or Sign Out** in that reference. The user has already selected the operation; resolve the exact connection before acting, and verify its outcome instead of treating the chat handoff as completion.
2. Check what is configured with `codex mcp list` and `codex mcp get hermios`.
3. If the default server is present, call `get_hermios_profile` and `open_hermios` to verify the signed-in identity and workspace. On older servers, use `list_object_metadata_names` to check access without inventing the account identity.
   - For the native interface, use `open_hermios` or the Hermios sidebar entry. Native settings belong to the signed-in user and workspace. CRM OAuth is separate from ChatGPT-plan access; read `../../references/chatgpt-plan.md` if the user asks to connect their plan inside Hermios.
4. For a second hosted workspace, run `bash scripts/setup-mcp.sh --name hermios-<workspace> https://api.hermios.app` from the plugin root. For self-hosted Hermios, pass that server's URL instead. Then have the user complete sign-in and choose the workspace.
5. Ask for the workspace subdomain (for example `acme` in `acme.hermios.app`) if it is not known yet; record links need it.
6. If a call fails, match the symptom to the troubleshooting table in `setup.md` and give the user the specific fix. Problems on the server side (Cloudflare Access, tunnel routes, `SERVER_URL`) need a Hermios admin. Say so plainly rather than retrying.

# Output

Finish with one line stating which Hermios server and workspace (subdomain) Codex is connected to, or the single next action the user must take.