OAuth Login

Claude Code and Codex both support Statewright browser sign-in, but own their credentials differently. Claude uses native MCP OAuth. Codex's device flow stores a verified gateway credential in the OS credential store. Neither consumer flow asks you to paste a key into a conversation.

Using Cursor, OpenCode, Pi, OMX, or a custom MCP host? Follow its installation guide for authentication. The two browser flows below are specific to Claude Code and Codex.

Connect Claude

1. Install the native plugin.
2. Open the Arbiter's connection status, then choose Connect.
3. Review Claude's native permission prompt and complete Statewright sign-in.
4. Return to the conversation and wait for the workflow list.

The same flow runs in the terminal and Desktop Code → Local. Claude manages saved credentials and refresh. An existing login can restore without another browser window. Session-scoped workflow-control consent is separate from login and from permission to execute a tool.

For SSH or a browserless host, run this in a separate terminal on the same machine and in the same Claude configuration scope:

claude mcp login plugin:statewright:statewright --no-browser

Open its link on a browser-capable computer. Paste the full callback URL into that terminal, then connect again in the original conversation. Do not paste it into chat. Native sign-in requires the Claude CLI; automatic browser sign-in also requires Expect. A key from the Codex credential store is not a substitute for Claude's native login.

Connect Codex

1. Install the Codex plugin and restart Codex.
2. Ask Codex to call statewright_connect.
3. Note the short-lived code in the tool response. Open the approval URL it returns if your browser did not open automatically.
4. Check that the browser displays the same code. Choose a sign-in provider and finish signing in.
5. Approve the Statewright connection. Return to Codex and wait for the tool to report success.
6. Ask Codex to list your workflows to confirm the connection.

The browser's “completed” page means you approved the request. Codex must still receive and verify the result before the connection is ready. Do not close the Codex session while it is waiting.

Over SSH, open the returned approval URL on another computer and match the device code. Unlike Claude's manual flow, Codex polls for completion; there is no callback URL to paste. On macOS, an interactive terminal can offer Keychain unlock/recovery if the store is locked. Never put the Keychain password in chat. Noninteractive hosts must arrange credential access before launch.

Optional telemetry

Statewright asks for one optional choice covering website session recordings and diagnostic reports from connected plugins. Older recording-only approvals do not enable plugin reports. Declining does not affect login, workflows or host permissions.

Basic website analytics through Umami runs independently of this choice.

When signed in, use Telemetry preferences on the website to save or withdraw the account choice. Plugins need a current grant from their gateway's account service; they do not inherit consent from Claude or OpenAI. Local opt-outs win: turn Diagnostic reports off in Claude's /statewright configure, or set STATEWRIGHT_SENTRY_DISABLED=true for Node-based integrations.

Plugin reports contain fixed failure/operation categories, version, platform and optional numeric status codes—not prompts, code, commands, credentials, account identifiers, paths or raw exception messages. Website recordings capture page interactions with form-input masking; receiving infrastructure still handles network data such as IP addresses.

Changes normally reach the website within a minute. Claude uses a grant verified within the last minute; Node reporters check the account service before sending. Unknown consent stays off. Pre-login and fatal-exit reporting require explicit local diagnostic opt-in; nothing is saved for later upload after login. See the complete telemetry behavior.

Multiple environments

For Claude, use /statewright configure to select Statewright gateway, then reload plugins and connect to that service. Its OAuth service must register the native statewright-claude client. Do not copy credentials between hosts or environments.

The Codex plugin stores a separate credential for each gateway in macOS Keychain, Windows Credential Manager, or Linux Secret Service. Production, staging, and named development profiles do not share credentials. Connect again in each environment you use. Selecting an unknown profile, or one without an authorization-service mapping, fails rather than silently using production.

For a non-production gateway, create ~/.statewright/environments.json with both its MCP endpoint and authorization service:

{
  "gateways": {
    "staging": {
      "gateway_url": "https://staging-gateway.example/mcp",
      "auth_url": "https://staging-accounts.example"
    }
  }
}

Start Codex with STATEWRIGHT_ENV=staging to select that profile, or set STATEWRIGHT_GATEWAY_URL to a configured endpoint. These URLs are deployment-specific; confirm the approval page belongs to the selected environment before signing in. An unknown profile or a gateway without an authorization-service mapping fails closed.

Troubleshooting

• No browser window appears: Use the exact approval URL returned by statewright_connect. It may have opened on another screen or in another browser.
• The code does not match or has expired: Do not approve it. Call statewright_connect again and use the new URL and code.
• The browser says “completed,” but Codex does not connect: Wait for the tool's result. If it reports an error, reconnect with a new request; browser completion alone is not a verified plugin connection.
• Credential storage is unavailable: Unlock your OS credential store and retry. Linux desktop sessions need a working Secret Service. Headless automation may use a process-scoped STATEWRIGHT_API_KEY; that is not a browser login.
• Claude says Check Claude permissions: inspect the native prompt or rule. An OAuth retry cannot resolve a permission denial; do not add blanket allow rules.
• A previously denied action still fails: Login does not replay it or waive workflow policy. Distinguish an authentication failure from a tool-policy refusal before deciding what is allowed next.

Web and other remote MCP hosts

ChatGPT web uses its own remote MCP connection, separate from the Codex CLI plugin and local Desktop launcher. The web host controls its model; a Statewright workflow cannot switch it. Do not infer a successful model handoff from a web workflow transition.

Remote MCP connections expose workflow tools within the connected host. They do not establish interception of all native tools. Configure authentication in the host's connection settings and verify the workflow list there; a Claude Code login does not establish a Claude web connection.