Codex Setup

How do I connect Codex to Controller AI?

Run cai agent setup --client codex, then finish Codex’s OAuth login. Verify its account inside Codex before you work on Support helper. Setup selects either a supported plugin or a direct MCP connection plus skills.

Inspect and apply the setup plan

In the app: open Controller AI’s Connect page and find Set up your coding agent. Select the copy icon beside the prompt, then paste the prompt into Codex.

With an assistant: install the CLI. This command prints the current setup as JSON without changing anything:

cai agent setup --client codex --status --json

Detection requires a codex executable on PATH. Installing the desktop app alone is not enough. These examples assume no workflow pin, because setup and agent inventory are not workflow-scoped. Once Codex is detected, apply the plan you inspected:

cai agent setup --client codex --yes --json

Without an interactive terminal, a plan with actions requires --yes. Otherwise setup changes nothing and returns error.code: "SETUP_CONFIRMATION_REQUIRED" with Setup was not changed. Rerun with —yes to approve the printed plan. Browser sign-in still requires you.

If the CLI credential is missing or was rejected, machine authorization runs first. Setup is not atomic. A failure leaves earlier authorization, MCP or marketplace changes in place. In a multi-client setup, a fatal error stops later clients. Inspect status before you retry. A same-name skill that setup does not manage stops installation with UNMANAGED_SKILL_EXISTS. Move the conflicting directory aside, then retry.

Which installation does setup choose?

By default, the released CLI has no marketplace source for installing a new Codex plugin. Setup reuses a plugin it recognizes as already installed. Otherwise it uses direct MCP plus skills. None of this establishes public-directory availability.

OpenAI supports plugins in Codex in the ChatGPT desktop app and Codex CLI, but not the IDE extension. After installation, start a new desktop conversation or CLI session.

Separate skills default to global. Controller’s codex target writes to the skills folder of the deprecated but supported CODEX_HOME compatibility directory. That folder is normally ~/.codex/skills, while Codex’s canonical user directory is ~/.agents/skills. --skills-scope project writes the current project’s .agents/skills.

For the direct fallback, these commands add the server, install the skills, and start the browser login:

codex mcp add controllerai --url https://mcp.getcontroller.ai/mcp
cai skills install --target codex --json
codex mcp login controllerai

A saved URL is not authenticated. Setup runs login when authentication is missing or unknown. Inspect data.results afterwards. A failed login is recorded without failing the overall setup command, so exit code 0 does not prove that OAuth succeeded. Complete the login, then call account_status.

Direct MCP shares one configuration across desktop, CLI, and IDE. In desktop, open Settings → MCP servers → Add server. In the IDE, use the gear menu → MCP servers → Add server. Name it controllerai, choose Streamable HTTP, and enter the URL above. Save it, select Restart on desktop or Restart extension in the IDE, then select Authenticate. Use these OpenAI MCP controls when terminal setup cannot detect your host.

At browser consent, select Allow full access or Continue read-only for the access you want. Full access is enabled only if it was requested, and read-only appears only if it was requested. Then choose My Controller account → Continue or Separate agent account → Use agent account. For your own account, check the signed-in email before selecting Connect account.

Verify Codex and the CLI separately

Inside Codex, call account_status with {}. Check user, account.kind, account.accessMode, and grantedScopes, which report Codex’s OAuth grant. The kinds are member, agent, or claimed. Unclaimed accounts return user.email: null. Unconfirmed and synthetic addresses are also hidden, so a null email alone does not prove an account mismatch.

For account.kind: "agent", explain that this separate account was created without email or password, and show its reported usage allowance. Offer account_claim_start with the owner’s email, then account_claim_verify with their six-digit code. Both require controller:full on /mcp. Claiming removes the unverified cap and enables email recovery. Call account_status again to check for claimed. Reauthorizing a separate account can continue the same identity.

For local evidence, run these commands and read their JSON:

cai auth status --json
cai doctor --json
cai agent setup --client codex --status --json
cai skills status --target codex --json

CLI authentication does not prove Codex MCP identity. Doctor checks CLI login, API access, workflow pin, runtime, and skills. Run it again after a repair. For project skills, run these checks from that project:

cai agent setup --client codex --skills-scope project --status --json
cai skills status --target project --json

Read guidance and check the inventory

Call guide_get with {"name":"controllerai-start"}. MCP stores no workflow pin. Pass workflowId on every workflow-scoped call, and supply instructions and file contents inline, never as local paths.

In the app: open Agents. You have no agents yet is a valid empty inventory, and that screen has no search control. Otherwise search for Support helper. All agents includes shared agents, while the query below returns only agents you own.

With an assistant: list existing matches without creating anything:

cai agent list --ownership mine --search "Support helper" --json

For Codex’s MCP connection, call agent_list with ownership: "mine" and search: "Support helper". Report names and IDs, or report no matches. Either successful result completes the inventory check.

Update Codex, the CLI and guides separately

Use Codex’s host controls for its connection, and Skills and updates for guidance maintenance. cai upgrade prints the CLI installation command and updates skills. It does not replace the CLI executable, and it does not update Codex.

These instructions are for external Codex. Controller AI’s in-product builder already has managed authentication and bundled guidance, so it must not install, connect, or upgrade itself.

Next: build Support helper or review Assistant access and security.