Codex · Advanced · Part 6 of 8
Extending Codex: MCP, subagents, skills, plugins, hooks, and choosing where to run it
So far Codex has worked inside your project folder with the tools it ships with. Real projects also live in issue trackers, documentation sites and browsers, and real developers live in editors. This part covers the extension layer: how to choose between AGENTS.md, rules, skills, MCP servers, subagents, hooks and plugins, how to add and manage each one, and then where Codex can run: your editor, the desktop app, the cloud, a remote machine, or a separate Git worktree. Details come from the official documentation; my own advice is marked as such.
- Pick the extension by the problem: always-on guidance goes in
AGENTS.md, command permissions in rules, repeatable workflows in a skill, outside systems in MCP, noisy side work in a subagent, automatic checks in hooks, and shared bundles in a plugin. - Add an MCP server with
codex mcp addor a[mcp_servers.<name>]table inconfig.toml. Check it with/mcp, and connect only servers you trust. - A subagent is a helper that does its own model and tool work and reports back. Ask for it directly. It costs more tokens, and it inherits your sandbox and approval settings.
- A skill is a folder with a
SKILL.mdfile. Repo skills live in.agents/skills; personal skills live in~/.agents/skills. - The IDE extension, desktop app, CLI and cloud share one configuration story but not every feature. The last tables in this part help you choose.
Codex changes quickly. This series was checked against the official documentation on 18 October 2026; always confirm details on the official pages linked at the end.
Contents of Part 6
- Which extension for which problem?
- MCP: connecting Codex to outside tools
- Subagents: helpers that work in parallel
- Skills: reusable workflows
- Plugins and the marketplace
- Hooks and rules: guardrails
- Your editor, desktop app, cloud and remote machines
- Worktrees: parallel chats in one repository
- Which surface should I use?
- Wrap-up and glossary
- Links and official docs
1. Which extension for which problem?
The official customization guide says these layers are “complementary, not competing”: AGENTS.md shapes behaviour, memories carry local context forward, skills package repeatable processes, and MCP connects Codex to systems outside the local workspace. It also suggests an order to build them in: AGENTS.md first (Part 2), then a plugin or skill when a reusable workflow exists, then MCP when a workflow needs an outside system, then subagents when you want to delegate noisy or specialised tasks. You do not need everything on day one. Here is the decision table I use. The “use it when” column follows the docs; the “do not use it when” column is my own reading of them.
| Tool | Use it when… | Do not use it when… |
|---|---|---|
| AGENTS.md | Codex keeps repeating a mistake, reads too many files, or you give the same pull request feedback twice. Build and test commands, review expectations, conventions. | The guidance is long, rarely needed, or a multi-step procedure. Keep this file small; move procedures to a skill. |
Rules (.rules files) | You want to decide which commands may run outside the sandbox: allow, prompt or forbid. Rules are marked experimental. | You want to teach Codex a coding convention. Rules control commands, not style. |
| Skill | A workflow is repeatable: release steps, a review routine, a docs update. It needs examples, references or helper scripts. | The instruction applies to every task (use AGENTS.md), or you need a live connection to a system (use MCP). |
| MCP server | Codex needs tools or data that live outside the repo: an issue tracker, design tool, browser, or shared documentation. | A plain command-line tool already does the job, or you cannot vouch for the server. |
| Subagent | A side task would flood the main chat with logs and search results, or independent read-heavy work can run in parallel. | The task is small, or several agents would edit the same files at once. Subagents use more tokens than a single-agent run. |
| Hook | Something must happen automatically at a lifecycle point: block a risky command, log activity, run a check when a turn stops. | You only need Codex to remember a preference (use AGENTS.md). Hooks run your code, so each one is a trust decision. |
| Plugin | You want to reuse or share a bundle of skills, MCP servers and other parts, or install a proven setup someone else built. | You are experimenting alone. Start with a skill folder and package it later. |
They combine well. The docs describe skills plus MCP as “where it all comes together”: the skill defines the workflow and names the MCP tools to use. The docs also say to pair AGENTS.md with infrastructure that enforces rules, such as pre-commit hooks, linters and type checkers.
2. MCP: connecting Codex to outside tools
The Model Context Protocol (MCP) lets Codex use tools and information from other systems. In the docs' words, an MCP server “describes the available tools and handles their requests”, for example looking up a ticket or retrieving documentation. The docs name three roles: the host is Codex, the client is the MCP connection inside Codex, and the server is the external tool or context provider. A server can expose tools (actions), resources (readable data) and prompts (reusable prompt templates). That split helps you judge trust: some servers only provide context, while others expose powerful actions.
Without a standard, every tool needs its own custom cable. MCP is the standard socket. Any service that offers an MCP server plugs into Codex the same way, and the server handles the details of talking to the real system.
Adding a server from the command line
For a server that runs as a local program (a stdio server), the documented form is below. Everything after -- is the command that starts the server. The docs' own example adds Context7, which they describe as a free MCP server for developer documentation:
codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>
# Example from the docs
codex mcp add context7 -- npx -y @upstash/context7-mcp
For a server you reach at an address (a streamable HTTP server), use --url instead of a command. The reference also lists --bearer-token-env-var, --oauth-client-id and --oauth-resource for HTTP servers.
codex mcp add example --url https://mcp.example.com
The commands to manage servers:
| Command | What it does |
|---|---|
codex mcp list | List configured servers. Add --json for machine-readable output. |
codex mcp get <name> | Show one server's configuration (--json prints the raw entry). |
codex mcp login <name> | Start an OAuth sign-in for an HTTP server that supports OAuth. |
codex mcp logout <name> | Remove stored OAuth credentials for that server. |
codex mcp remove <name> | Delete the stored server definition. |
/mcp (inside the TUI) | Show your active MCP servers and tools. /mcp verbose adds server diagnostics; /mcp login <name> signs in from the session. |
Adding a server in config.toml
Codex stores MCP configuration in config.toml next to its other settings: by default ~/.codex/config.toml, or a project-scoped .codex/config.toml (trusted projects only). The ChatGPT desktop app, the CLI and the IDE extension share this configuration, so you set a server up once and switch between clients. Each server is a [mcp_servers.<name>] table. This is the docs' own Context7 example:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"For an HTTP server, give url instead of command. The docs' example uses an environment variable for the token, so the secret is not written into the file:
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
A few other documented options, all optional:
enabled = falseturns a server off without deleting it.required = truemakes startup fail if that server cannot start.enabled_toolsis an allow list of tools;disabled_toolsis a deny list applied after it.default_tools_approval_modesets how tools from this server are approved:auto,prompt,writes(prompts for tools not marked read-only) orapprove. A per-toolapproval_modeoverrides it.startup_timeout_sec(default 10) andtool_timeout_sec(default 60) limit how long a server may take.
You can also add servers in the apps. In the desktop app open Settings, then MCP servers, then Add server, enter a name, choose STDIO or Streamable HTTP, and save. The IDE extension has the same flow under the gear menu. For OAuth servers, select Authenticate when prompted.
A safe first server
- Pick a read-only, documentation-style server. Context7 in the docs' example only fetches developer documentation. Start there, not with a server that can write to your systems.
codex mcp add context7 -- npx -y @upstash/context7-mcp - Check it is registered.
codex mcp list - Confirm Codex can see it. Start
codexand type/mcp. - Try one question that needs current documentation, and watch which tools Codex asks to use.
- Turn it off when you do not need it. Set
enabled = falsein itsconfig.tomltable, or runcodex mcp remove context7.
- An MCP server is code you run, or a service that receives what Codex sends it. The docs say that when a plugin sends data through an MCP server, that service's terms and privacy policy apply.
- Text that comes back from a server is content Codex reads. Treat web pages, tickets and documents as untrusted, because hidden instructions in them can try to steer an agent (this is called prompt injection).
- Project-scoped
.codex/config.tomlloads only for trusted projects. Do not mark a stranger's repository as trusted just to try it. - Keep secrets out of files you commit. Use
bearer_token_env_varorenv_varsto pass them by environment variable. If you register an OAuth client secret, the docs warn that Codex saves it inconfig.toml, which you must keep private and out of version control. - Use
enabled_toolsanddefault_tools_approval_mode = "prompt"when a server offers more tools than you need.
The docs list some commonly used servers, including OpenAI Docs MCP, Context7, Figma, Playwright, Chrome Developer Tools, Sentry and GitHub. I have not tested them here; check each one's own page before connecting it.
3. Subagents: helpers that work in parallel
A subagent workflow is one where Codex spawns specialised agents in parallel and collects their results in one response. The docs' reason for it is context. If the main chat, where you set requirements and decisions, fills with exploration notes, test logs and stack traces, the session becomes less reliable over time. The docs call this context pollution and context rot. Subagents move the noisy work off the main thread and send back summaries instead of raw output.
Current Codex releases enable subagent workflows by default, and subagent activity shows up in the desktop app, the CLI and the IDE extension. Two honest caveats from the docs: subagent workflows use more tokens than a comparable single-agent run, because each subagent does its own model and tool work; and parallel agents are best for read-heavy tasks such as exploration, tests, triage and summarisation. Be more careful with parallel write-heavy work, because agents editing code at once can create conflicts.
How to ask for one
Current local Codex releases delegate when you ask directly, or when applicable AGENTS.md or skill instructions request it. The docs' advice for a good prompt: explain how to divide the work, whether Codex should wait for all agents, and what summary to return. This is their example:
Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.
- In the CLI: use
/subagentsto inspect and switch between agent threads while they run. The main thread collects the results into its final response. Approval requests can come from inactive agent threads; the overlay shows the source thread and you can press o to open it. - In the desktop app: each subagent thread is surfaced so you can inspect its work and the summary it returned.
- In the IDE: when the background-agent panel is available, active subagents appear above the composer, where you can see status, stop all, or open one.
- Steering and stopping: ask Codex directly to steer a running subagent, stop it, or close completed agent threads.
Permissions and models
- Subagents inherit the parent turn's sandbox and approval settings, including changes made with
/permissionsor--yolo. A custom agent file cannot replace them, and agent instructions that say “do not edit” do not create a separate read-only sandbox. Choose the permission mode before you ask Codex to delegate. - In non-interactive runs, an action that needs a new approval fails and the error goes back to the parent workflow.
- Model and effort: if you set nothing, a subagent inherits the parent's model and reasoning effort. You can request one in your prompt, set
[agents]defaults, or setmodelandmodel_reasoning_effortin a custom agent file. The docs suggestgpt-6.1-solfor demanding agents (where your account has access) andgpt-6-lunaas a faster, lower-cost option for narrow work. Higher reasoning effort raises response time and token use. Model availability changes, so check Part 4 and the models page.
Custom agents
Codex ships built-in agents: default (general-purpose fallback), worker (implementation and fixes) and explorer (read-heavy exploration). To define your own, add one standalone TOML file per agent under ~/.codex/agents/ (personal) or .codex/agents/ (project). Every file must define name, description and developer_instructions. A custom agent can change model settings and instructions, but it inherits the parent's permissions, provider and MCP servers, and it cannot override them. Configure MCP servers in the parent session. If a custom agent has the same name as a built-in one, yours wins. This is adapted from the docs' PR review example:
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""Global limits live under [agents] in config.toml. The documented fields are agents.enabled (default true), agents.max_concurrent_threads_per_session, agents.default_subagent_model, agents.default_subagent_reasoning_effort and agents.interrupt_message. The docs' advice on design: the best custom agents are narrow and opinionated, with one clear job.
4. Skills: reusable workflows
A skill is a directory with a SKILL.md file plus optional scripts, references and assets. Skills build on an open agent skills standard (see the link section). The docs use the idea of progressive disclosure to keep context small: Codex starts with each skill's name and description, loads the full SKILL.md only when it chooses that skill, and reads references or runs scripts only when needed. In Codex the initial list also includes each skill's file path, and by default it uses at most 2% of the model's context window (8,000 characters when the window is unknown); if you install many skills, Codex shortens descriptions first and may omit some with a warning.
The SKILL.md format
SKILL.md must include name and description in a short header. The instructions follow. This is the docs' own example:
---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---
1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.Where skills live
| Scope | Location | Use it for |
|---|---|---|
| Repo | .agents/skills (Codex scans it in every directory from your working directory up to the repository root) | Workflows for this project, checked in for your team |
| User | $HOME/.agents/skills | Your personal skills, available in every repo |
| Admin | /etc/codex/skills | Shared defaults on a machine or container |
| System | Bundled with Codex | Skills such as skill-creator and plan |
If two skills share the same name, Codex does not merge them. Symlinked skill folders are supported. Codex detects skill changes automatically; if an update does not appear, restart Codex.
Creating and using a skill
- Let Codex draft it. The built-in creator asks what the skill does, when it should trigger, and whether it should stay instruction-only (the default) or include scripts.
$skill-creator - Or write it yourself. Create a folder with a
SKILL.mdfile under.agents/skills/<skill-name>/in your repo. - Write a precise description. Codex chooses implicitly by matching your task to the
description, so state when the skill should and should not trigger, and put the key use case first. - Invoke it. In the CLI or IDE extension, run
/skillsor type$to mention a skill explicitly. Codex can also pick it on its own. - Install curated skills for local use with
$skill-installer, for example$skill-installer linear.
- Optional metadata: an
agents/openai.yamlfile can set display details, an invocation policy and tool dependencies. Withallow_implicit_invocation: false(default istrue), Codex will not pick the skill on its own, but an explicit$skillstill works. - Disable without deleting: add a
[[skills.config]]entry with the skill'spathandenabled = falseto~/.codex/config.toml, then restart Codex. - The docs' best practices: keep each skill focused on one job, prefer instructions over scripts unless you need deterministic behaviour, write imperative steps with explicit inputs and outputs, and test prompts against the description.
- Cloud: skills stored in your repository are available in cloud tasks, but personal skills from your computer are not synced to cloud environments.
5. Plugins and the marketplace
Plugins bundle capabilities into reusable workflows. According to the docs they can include skills, MCP servers, browser extensions and hooks. Skills stay the authoring format; plugins are the installable distribution unit. ChatGPT and Codex use one universal plugin directory, so the same public plugins are discoverable from their supported surfaces.
Where plugins work: plugins work in Codex in the ChatGPT desktop app, and the Codex CLI has its own plugin browser. The IDE extension does not support plugins. If you work alone on one project, you can skip this section for now: AGENTS.md, a few skills and a couple of MCP servers go a long way.
Install and manage plugins
- Open the browser. In the desktop app, open the Plugins tab. In the CLI, start
codexand type/plugins. The CLI browser groups plugins by marketplace; use the marketplace tabs to switch sources, open a plugin to inspect details, install or uninstall it, and press Space on an installed plugin to turn it on or off.codex /plugins - Install one. In the app, search or browse, open the details and select the plus button. Connect any MCP server when prompted; some plugins ask you to sign in during install, others wait until first use.
- Start a new session. Bundled skills and tools become available when you start a new chat or CLI session after installing.
- Use it. Describe the task, or type
@to pick the plugin or one of its skills explicitly.
From a shell, the documented commands are:
| Task | Command |
|---|---|
| Install a plugin from a configured marketplace | codex plugin add <plugin> (use --marketplace NAME or -m NAME, or write plugin@marketplace) |
| List installed plugins | codex plugin list (--json for scripts) |
| Remove an installed plugin | codex plugin remove <plugin> |
| Add a marketplace | codex plugin marketplace add owner/repo |
| See marketplaces in use | codex plugin marketplace list |
| Refresh Git marketplaces | codex plugin marketplace upgrade (optionally with a marketplace name) |
| Remove a marketplace | codex plugin marketplace remove <name> |
Marketplaces
A marketplace is, in the docs' words, a JSON catalog of plugins. codex plugin marketplace add accepts GitHub shorthand (owner/repo or owner/repo@ref), HTTP or HTTPS Git URLs, SSH Git URLs, or a local marketplace root directory. These examples are from the docs:
codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root
Use --ref to pin a Git ref. Repeat --sparse PATH for a sparse checkout; it is valid only for Git sources. To keep your own curated list, the docs use $REPO_ROOT/.agents/plugins/marketplace.json for a repo-scoped list or ~/.agents/plugins/marketplace.json for a personal one, with one entry per plugin under plugins[]. Administrators can define marketplaces in system or cloud-managed configuration (Part 7 touches on team setup).
Building a plugin
The docs' fastest path is the built-in plugin creator: $plugin-creator in Codex. It scaffolds a .codex-plugin/plugin.json manifest and can create a local marketplace entry for testing. Only that manifest is always created; .mcp.json, skills/, hooks/, scripts/ and assets/ are optional. For a portable package you can write a root plugin.json by hand. The packaging guide is linked at the end; I recommend reading it in full before you publish anything, because the manifest layouts have two supported forms.
- A plugin can bring skills, MCP servers and hooks. The docs say to review and trust plugin hooks before they run, and that when a plugin capability runs through a Codex host, that host's sandbox and approval policy still applies.
- Uninstalling removes the plugin bundle from that environment. Separately connected MCP integrations remain connected until you disconnect them.
- If you sign in to Codex with an API key, you can still browse and manage supported OpenAI-curated plugins, but some plugins are unavailable because their connection flows need unsupported OAuth capabilities.
- Plugins marked Desktop only need the ChatGPT desktop app.
6. Hooks and rules: guardrails
Hooks are an extensibility framework: they run your scripts (or MCP tools) at set points in the agent loop. The docs list uses such as logging a chat, scanning prompts to block accidentally pasted API keys, running a custom check when a turn stops, or customising prompting in a certain directory. The events include PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, Stop, SessionStart, SessionEnd, SubagentStart and SubagentStop, among others.
- Where they live:
hooks.jsonor inline[hooks]tables inconfig.toml, in the user layer (~/.codex/) or the project layer (<repo>/.codex/). Project-local hooks load only when the project.codex/layer is trusted. Plugins can bundle hooks too. - Trust is required. Before a non-managed hook can run, Codex requires you to review and trust the exact hook definition. Trust is recorded against the hook's hash, so new or changed hooks are skipped until you trust them again. Use
/hooksin the CLI to inspect sources, review hooks, trust them, or disable individual ones. - All matching hooks run, and several for the same event start concurrently.
commandandmcp_toolhandlers are supported. - Timeouts:
timeoutis in seconds; if omitted, most hooks use 600.
A trimmed version of the docs' hooks.json shape, which runs a policy script before any Bash command:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
"statusMessage": "Checking Bash command"
}
]
}
]
}
}The script itself is yours to write; the docs describe what it receives and may return. The docs also advise resolving repo-local hook paths from the git root, because Codex may be started from a subdirectory. A hook is code that runs on your machine, so treat adding one like adding a dependency. For one-off automation where you vet hook sources elsewhere, --dangerously-bypass-hook-trust skips the persisted-trust requirement; the name is a hint to avoid it otherwise.
Rules: control which commands leave the sandbox
Rules answer a narrower question: which commands may run outside the sandbox? Create a .rules file in a rules/ folder next to an active config layer, for example ~/.codex/rules/default.rules, then restart Codex. Each rule is a prefix_rule with a pattern and a decision of allow, prompt or forbidden. When several rules match, the most restrictive wins (forbidden beats prompt beats allow). This is the docs' example:
prefix_rule(
pattern = ["gh", "pr", "view"],
decision = "prompt",
justification = "Viewing PRs is allowed with approval",
match = ["gh pr view 7888", "gh pr view --repo openai/codex"],
not_match = ["gh pr --repo openai/codex view 7888"],
)The match and not_match lists are inline tests that Codex checks when it loads the file. You can also test a rule file before relying on it with codex execpolicy check --pretty --rules ~/.codex/rules/default.rules -- gh pr view 7888. Rules and the execpolicy command are labelled experimental, so expect change. Project-local rules load only for trusted projects.
7. Your editor, desktop app, cloud and remote machines
Codex runs in several places. The CLI, the IDE extension and the desktop app share the same configuration layers, so your config.toml and MCP servers carry across. What changes is where the work runs and how you interact with it.
The IDE extension
- Install: choose your IDE on the official page. VS Code, Cursor and Windsurf use the Codex extension (identifier
openai.chatgptin the Visual Studio Marketplace). Xcode and JetBrains IDEs provide their own integrations, where you choose Codex as the agent in the coding assistant or AI Chat. - Open it: in VS Code, Cursor or Windsurf choose the Codex icon; if it is not visible, open the Command Palette and run Codex: Open Codex Sidebar. Then open a project and ask Codex to explain the codebase, make a focused change or debug something. The docs suggest creating Git checkpoints before and after a task so you can revert.
- What it adds: your open files and selection become context for the prompt, you review edits beside the code, and you can delegate a longer task to Codex in the cloud.
- Commands (Command Palette):
chatgpt.newChat,chatgpt.newCodexPanel,chatgpt.addToThread(selected range as context),chatgpt.addFileToThread,chatgpt.openCommandMenuandchatgpt.openSidebar. You can bind them to shortcuts. - Slash commands (type
/in the composer):/status,/model,/reasoning,/plan,/review,/compact,/fork,/init,/mcp,/local,/cloud,/cloud-environment,/worktree,/side,/goal,/memoriesand more. The full table is in the IDE slash-command docs. - Settings: two layers. Agent behaviour (model, reasoning effort, permissions, sandbox, MCP servers) lives in
config.toml: select the gear icon, then Codex Settings, then Open config.toml. Editor behaviour useschatgpt.*keys in your editor's settings, for examplechatgpt.openOnStartup,chatgpt.followUpQueueMode(queueorsteer),chatgpt.composerEnterBehaviorandchatgpt.reviewDelivery(inlineordetached). Do not putchatgpt.*keys inconfig.toml. - Windows:
chatgpt.runCodexInWindowsSubsystemForLinuxruns Codex in WSL when available. - Limits: plugins are not supported in the IDE extension, and it does not render visualizations.
The desktop app
- What it is: the ChatGPT desktop app, available for macOS, Windows and Linux, where you select Codex from the ChatGPT dropdown for software development. You can start a chat, create a project, or open a folder.
- Why people use it: several projects and long-running chats in one place, the Plugins tab, a Skills view in the sidebar, MCP servers under Settings, worktrees, scheduled tasks, and keyboard shortcuts you can customise under Settings > Keyboard Shortcuts.
- From the terminal:
codex applaunches the desktop app on macOS or Windows.
Codex cloud
Codex cloud runs coding tasks in the cloud, so work can continue while your computer is asleep. You use it on the web, on mobile, or in the desktop app.
- Create a cloud environment. An environment is the reusable setup tasks use: repositories, dependencies, tools and access settings. In a new task choose Work in > Cloud, open Select environment, then Create environment. Select your GitHub repositories (connect GitHub if prompted) and choose Get started. Codex inspects the repositories, installs dependencies and tools, and tests the workflow.
- Review and publish. Check the setup report, save, and select Publish. The docs note that saving stores configuration, while publishing captures the prepared filesystem for new tasks. Environments can record an install script and a start skill.
- Delegate a task. Choose the published environment, describe the work, and send it. Each new task gets its own isolated workspace. From the IDE, the
/cloudand/cloud-environmentslash commands run a chat in the cloud and choose its environment. From a terminal,codex cloudopens an interactive picker,codex cloud exec --env ENV_ID "<task>"submits a task, andcodex cloud listshows recent cloud chats. The docs labelcodex cloudexperimental. - Get results back. Review the changed files and test results, ask for follow-ups, then commit or open a pull request. To bring a cloud chat's most recent diff into your local repository, run
codex apply <TASK_ID>; it exits non-zero ifgit applyfails, for example on conflicts. Reopen the same task from the web, mobile or desktop app to continue it. Saved VM state is recoverable for up to seven days after you last started a turn. Commit important work, because saved state does not replace source control.
Internet access and secrets
- Internet access is a setting on the environment. Turn on Allow Codex to access internet, then under Allow domains choose Package managers or Custom domains only and add hosts under Additional allowed domains. All (unrestricted) exists for workflows that need broader access. Allowing a domain does not give Codex credentials or permissions in that service.
- Legacy cloud environments state that agent internet access is off by default (setup scripts still have internet access). The docs list risks of enabling it: prompt injection from untrusted web content, code or secret exfiltration, malware or vulnerable dependencies, and licence-restricted content. Allow only the domains you need.
- Environment variables versus network secrets: a variable is passed directly to programs. A network secret is a credential sent to a specific HTTPS service; programs receive a placeholder and a proxy substitutes the real value for allowed destinations, so the raw credential does not sit in a local process or file.
- Defaults and limits: as documented in October 2026, default VMs are 2 vCPUs, 8 GiB memory and 8 GiB disk on Plus, and 4 vCPUs, 16 GiB and 32 GiB on Pro, Business and Enterprise. Computer and browser use are not currently supported in cloud environments. GitLab and self-hosted GitHub Enterprise Server are also on the roadmap, not supported. Check the cloud environments page for current numbers.
Remote connections
Remote connections let you reach work that runs on another machine. The connected host provides the repository files, shell commands, MCP servers, skills and credentials, and its sandbox and approval settings still apply.
- From your phone: in the ChatGPT mobile app open Codex (some apps still label it Remote) to work with chats on a connected Mac or Windows desktop. On the host, go to Settings > Connections > Control this Mac or PC and follow the setup, which shows a QR code to scan. Setup starts from the desktop app, not from the CLI or IDE extension. The host must be awake, online, and signed in to the same account and workspace.
- What you can do remotely: start or continue chats, steer active work, approve commands, review diffs and test results, and get notified when a task finishes or needs attention.
- SSH hosts: in the desktop app you can add remote projects from an SSH host. Add a
Hostentry to~/.ssh/config, confirm you cansshto it, install and authenticate Codex on the remote host socodexis on its login-shellPATH, then open Settings > Connections, enable the host and choose a remote project folder. Chats then run commands and write changes on the remote host. - Handoff between hosts moves a chat and its Git state between your computer and a connected remote host. Handoff to a Codex cloud environment is not supported.
- Security: keep SSH hosts configured as you would for normal SSH, with trusted keys and least-privilege accounts. Do not expose app-server transports on a shared or public network; use a VPN or mesh networking tool to reach a remote machine.
8. Worktrees: parallel chats in one repository
A Git worktree is a second checkout of your repository that shares the same .git metadata. In the desktop app, worktrees let Codex run several independent chats in the same project without interfering with each other. They only work in projects that are part of a Git repository.
Your local checkout is the desk you sit at. A worktree is another desk with its own copy of every file, but all desks share the same filing cabinet of commits and branches. Codex can work at the second desk while you keep working at yours.
- Choose Worktree. In the new chat view, select Worktree under the composer. You can optionally choose a local environment to run setup scripts.
- Pick the starting branch below the composer:
main, a feature branch, or your current branch with uncommitted local changes. - Send your prompt. Codex creates the worktree. By default it works in a detached HEAD, so your branches are not cluttered.
- Decide where to continue. Use Create branch here in the chat header to turn the worktree into a branch you can commit, push and open a pull request from, or use Hand off to move the chat and its code to your Local checkout.
- One branch, one place: Git allows a branch to be checked out in only one worktree at a time. If you create
feature/aon a worktree, you cannot check it out locally. Use Handoff instead. - Ignored files do not move. Handoff uses Git, so
.gitignored files do not follow the chat. List ignored files that new managed worktrees need, such as.env, in a.worktreeincludefile at the repository root. Codex copies only matching ignored files, and it automatically copies an ignoredAGENTS.override.md. - Where and how many: managed worktrees live under
$CODEX_HOME/worktreesby default; you can change the root under Settings > Worktrees. Codex keeps your most recent 15 managed worktrees by default and saves a snapshot before deleting one. Permanent worktrees are not deleted automatically. - CLI and IDE:
codex exec --worktree "implement the next step"runs in a managed worktree (local execution only). The IDE has/worktree. Scheduled tasks can also run on dedicated background worktrees in Git repositories (Part 7).
9. Which surface should I use?
| Surface | Runs on | Choose it when… |
|---|---|---|
| Terminal (CLI) | Your machine | You want scripting, codex exec, the plugin browser and slash commands like /hooks and /subagents, and the closest view of what Codex does. |
| IDE extension | Your machine (cloud on request) | You live in the editor and want open files and selections as context, and in-place review. Not for plugins. |
| Desktop app | Your machine, or an SSH host | You want projects, parallel chats, worktrees, plugins, scheduled tasks and a visual workspace. |
| Codex cloud | OpenAI-managed VMs | The task is long, can run while your computer sleeps, or needs the same prepared setup across tasks. You must connect GitHub, and the environment needs its own internet and secrets settings. |
| Remote connection | A connected Mac, Windows PC or SSH host | You want to approve, steer and review work from your phone while it runs on a machine that has your tools and credentials. |
| Worktree | Your machine or a remote host, inside the desktop app | You want a second, isolated copy of the repository for a parallel chat without disturbing your current branch. |
You can mix them. Because the CLI, IDE extension and desktop app share configuration, a common pattern is to explore in the editor, send a heavy job to the cloud, and bring the diff back with codex apply. My own advice: pick one surface and get fluent in it first (the CLI if you followed Part 1); extra surfaces are easy to add later. The daily habits in Part 5 apply on every surface.
10. Wrap-up and glossary
- Add extensions when a recurring problem appears, not before. Start with
AGENTS.md. - MCP connects outside systems. Trust each server, keep secrets in environment variables, and use approval modes and tool allow lists.
- Subagents protect the main thread and run in parallel, but they cost more tokens and inherit your sandbox and approvals.
- Skills are folders with a
SKILL.md; plugins package skills, MCP servers and more for sharing; marketplaces are catalogs of plugins. - Hooks run your code and rules gate commands. Review and trust every hook, and test every rule.
- The surface changes where Codex runs and how you interact with it. Cloud tasks need an environment; worktrees need Git.
Part 7 moves from one developer to many: running Codex non-interactively in scripts and CI, scheduled tasks, and setting it up for a team or organisation.
| Term | In plain words |
|---|---|
| MCP | Model Context Protocol, a standard way to connect Codex to outside tools and context. |
| MCP server | A local program (stdio) or web service (streamable HTTP) that offers Codex tools for one outside system. |
| Prompt injection | Hidden instructions in content (a web page, a ticket) that try to steer an AI. |
| Subagent | A delegated agent that Codex starts for one task and that reports back to the main thread. |
| Skill | A folder with a SKILL.md file describing a repeatable workflow. |
| Plugin / marketplace | An installable bundle of skills, MCP servers and more, and a catalog of such bundles. |
| Hook | A script or MCP tool that runs at a lifecycle point, such as before a tool call. |
| Cloud environment | The reusable setup (repositories, tools, access) that Codex cloud tasks start from. |
| Worktree | A second checkout of a Git repository that shares its commit history. |
| Handoff | Moving a chat and its Git state between Local and a worktree, or between hosts. |
Links and official docs
Codex changes quickly. This series was checked against the official documentation on 18 October 2026; always confirm details on the official pages.
- Customization overview
- Model Context Protocol in Codex
- Subagents
- Build skills and the agent skills standard
- Plugins and Package your plugin
- Hooks and Rules
- Codex IDE extension, its settings and commands
- ChatGPT desktop app and Worktrees
- Codex Cloud and cloud environments
- Remote connections
- openai/skills on GitHub