OpenAI Codex - Reference Manual

French working version translated into English, based on the official OpenAI Codex documentation and the DEC/VSI documentation presentation.

Preface

This reference manual describes the functions of OpenAI Codex. It is not a step-by-step user guide. Commands, menus, and files are mentioned only to identify the functions they expose.

Codex is OpenAI's software development agent. It assists with programming, code analysis, review, defect correction, migration, documentation, testing, and automation of development work.

Audience

This manual is intended for developers, maintainers, technical leads, review teams, and administrators who need to know the functions available in Codex and the limits of each execution surface.

Document structure

This manual contains the following chapters:

Chapter 1: functional presentation of Codex.
Chapter 2: execution surfaces.
Chapter 3: models, reasoning, and context.
Chapter 4: tools and code operations.
Chapter 5: customization.
Chapter 6: security, sandboxing, and approvals.
Chapter 7: automation and integrations.
Chapter 8: reference objects.
Chapter 9: command and configuration entries.
Chapter 10: functional matrix.

The main official sources are the OpenAI Developers pages for Codex Overview, Codex Quickstart, Codex app features, Codex CLI features, Codex customization, and the pages related to configuration, permissions, sandboxing, MCP, skills, hooks, plugins, subagents, and automations.

Conventions

File names, options, commands, variables, and identifiers are shown in monospace. The terms App, CLI, IDE Extension, Web, Local, Worktree, and Cloud designate official Codex surfaces and modes.

1. Functional overview

Codex provides an interactive agent that can read a workspace, reason about its contents, propose a plan, modify files, execute commands, verify results, and report on its work.

Main functions include:

code generation and modification;
understanding and explaining codebases;
reviewing changes;
diagnosing and correcting errors;
running local or remote commands depending on the surface;
producing and verifying artifacts;
managing parallel tasks;
interacting with external tools;
automating recurring tasks.

Codex applies the thread instructions, project guidance, configuration rules, and security constraints available in the active environment.

2. Execution surfaces

2.1 Codex App

The Codex App is a desktop application for macOS and Windows. It provides an experience centered on Codex threads, projects, worktrees, automations, and integrated Git functions.

It includes a project list, project-specific discussion threads, Local, Worktree, and Cloud modes, an integrated terminal for each thread, a Git diff panel, common Git functions, an integrated browser, artifact support, and support for skills, MCP, notifications, memories, and automations.

2.2 Codex CLI

The CLI client provides a full-screen terminal interface and non-interactive subcommands. It supports working from a local directory, resuming sessions, and running Codex in automated workflows.

CLI functions include interactive conversational mode, launch with an initial prompt, resuming previous sessions, model selection, output display and copying, prompt history, non-interactive execution, the app server, and remote mode.

2.3 IDE Extension

The IDE extension places Codex inside the editor. It provides context from open files and allows tasks to be run directly from the editor project.

It supports default agent mode, reading and editing within the project directory, synchronization with the Codex App when both surfaces are open on the same project, IDE commands, slash commands, and automatic context from viewed files.

2.4 Codex Web and Cloud

The Web surface allows Codex tasks to run in configured cloud environments. Cloud environments decouple execution from the local machine and support parallel or delegated tasks.

Cloud functions depend on environment configuration, repository access, network policies, and active integrations.

2.5 Local, Worktree, and Cloud modes

Local mode works in the current project directory. Worktree mode isolates changes in a separate Git worktree. Cloud mode runs work in a configured remote environment.

Local and Worktree modes run on the user's computer. Worktree mode provides Git isolation between current work and changes produced by Codex.

3. Models, reasoning, and context

3.1 Models

Codex uses OpenAI models suited to development tasks. The official documentation identifies gpt-5.5 as the recommended model for most Codex tasks, with emphasis on complex coding, tool use, planning, and multi-step work.

Model availability depends on the plan, surface, and account permissions.

3.2 Reasoning

Codex can decompose a request, establish a plan, read relevant files, make modifications, run checks, and adjust its work based on the results obtained.

Reasoning is constrained by accessible context, system and user instructions, project rules, available tools, permissions, the sandbox, and the approval policy.

3.3 Conversation context

A Codex thread preserves messages, decisions, plans, and results relevant to the current work. Sessions can be resumed when the surface supports it.

Context may include the current prompt, previous messages, contents of files that were read, command outputs, provided images or documents, project guidance, and data from connected tools.

3.4 Memories

When available, memories carry stable information across threads, such as preferences, project conventions, or recurring habits. They complement project guidance but do not replace explicit thread instructions.

4. Tools and code operations

4.1 Reading and modifying files

Codex can read accessible files, analyze their structure, and produce changes. Modifications are limited by the workspace, sandbox, and granted permissions.

4.2 Command execution

Codex can execute commands through the active surface, including commands to inspect a project, run tests, start a local server, format code, or verify a result. Execution is subject to approvals and sandbox restrictions.

4.3 Code review

Codex provides a review function that searches for defects, regressions, behavioral risks, and test gaps. In the Codex App, the diff panel can be used to inspect changes, comment on lines, and request fixes.

4.4 Git

Codex integrates or uses Git functions depending on the surface: diff display, staging, commit, push, pull request creation, worktree work, and repository state inspection.

4.5 Integrated terminal

In the Codex App, each thread has a terminal associated with the project or worktree. This terminal provides a local channel for verification and project operation commands.

4.6 Integrated browser and Browser Use

The Codex App provides an integrated browser to preview, comment on, and verify local pages, file previews, or public pages that do not require login.

Browser Use allows Codex to operate certain pages, including local development servers and file previews, when the required permissions and plugins are available.

4.7 Computer Use

Computer Use allows Codex to interact with macOS or Windows applications by seeing, clicking, and typing. This function targets desktop application testing, GUI issue reproduction, and flows not accessible through an API or plugin.

4.8 Image inputs and image generation

Codex accepts images as context. It can also generate or edit images in a thread when the function is available, especially for interface assets, illustrations, placeholders, or sprites.

4.9 Non-code artifacts

Codex can produce and verify artifacts such as PDFs, documents, spreadsheets, and presentations. The Codex App can display these artifacts in the task sidebar.

5. Customization

5.1 AGENTS.md

AGENTS.md provides durable guidance for a repository or a part of a repository. Files closest to the working directory take precedence over more general files.

AGENTS.md is used to describe build and test commands, coding conventions, review expectations, paths or files to prefer, and instructions specific to a tree.

5.2 Configuration

Codex can be configured through configuration files, environment variables, and surface settings. Configuration covers models, approvals, sandboxing, tools, MCP, hooks, and execution preferences.

5.3 Skills

Skills are reusable capabilities defined by a directory containing a SKILL.md file and, optionally, scripts, references, and assets.

They make it possible to encapsulate repeatable workflows, domain expertise, templates and resources, validation procedures, and indirect integrations through MCP.

5.4 Plugins

Plugins are distributable units that can include skills, tools, MCP servers, hooks, assets, or applications. They are used to package shareable capabilities.

5.5 MCP

The Model Context Protocol connects Codex to external tools and systems. MCP configurations are shared between the Codex App, CLI, and IDE extension when supported by the surface.

5.6 Hooks

Hooks attach processing to Codex lifecycle events. They are used to apply or verify technical policies around agent operations.

5.7 Subagents

Subagents are specialized agents to which Codex can delegate parts of the work. They are intended for tasks that benefit from specialized expertise or context.

6. Security, sandboxing, and approvals

6.1 Sandbox

The sandbox defines the resources accessible to Codex: readable files, writable locations, network access, and other execution capabilities. By default, Codex limits its work to the active project when the surface supports it.

6.2 Approvals

Approvals determine which operations require user confirmation or automatic review. They can be granted for a single action or for a broader scope depending on the surface and policy.

6.3 Permissions

Permissions control access to files, commands, networks, local applications, and external tools. Permissions may come from local configuration, administrator policy, or user approval.

6.4 Network

Network access may be disabled, limited, cached, or granted depending on the mode. First-party web search is available in some surfaces and may use cached or live results depending on configuration.

7. Automation and integrations

7.1 Automations

Automations run recurring or scheduled tasks. They can produce reports, check errors, monitor changes, or continue follow-up work.

Thread automations preserve the context of a specific conversation. Project or standalone automations run recurring work from a defined starting context.

7.2 Non-interactive mode

Non-interactive mode allows Codex to run in scripts or integration pipelines. It is suitable for tasks defined by a prompt and configuration.

7.3 Codex SDK

The Codex SDK provides a programming interface for integrating Codex into application workflows or internal tools.

7.4 App Server and remote mode

The app server allows a Codex client to connect to a remote server through WebSocket or a local socket, with appropriate authentication mechanisms.

7.5 GitHub, Slack, and Linear integrations

Integrations connect Codex to collaboration and tracking systems. Their availability depends on installation, account permissions, and organization configuration.

8. Reference objects

8.1 Project

A project associates Codex with a directory or repository. It defines the main work perimeter.

8.2 Thread

A thread is an operational conversation with Codex. It contains the requests, responses, plans, outputs, and modifications associated with a task or series of tasks.

8.3 Worktree

A worktree is a separate Git working copy used to isolate changes from a thread from the main directory.

8.4 Chat

A chat is a thread that does not necessarily depend on a project folder or repository. It is suitable for research, planning, and connected-tool workflows.

8.5 Skill

A skill is a reusable module of instructions and resources selected by Codex when a task matches its description.

8.6 Plugin

A plugin is an installable package that groups Codex capabilities.

8.7 MCP server

An MCP server exposes external tools, resources, or actions to Codex.

8.8 Hook

A hook is processing associated with a Codex event.

8.9 Automation

An automation is a scheduled or recurring execution of a Codex instruction.

8.10 Sandbox

The sandbox is the set of access limits applied to Codex actions.

9. Command and configuration entries

This chapter describes the main functional entries. It is not a usage procedure.

9.1 The `codex` command

The codex command is the main entry point for the terminal client. It opens an interactive session when launched without a subcommand and accepts an initial prompt when text is provided.

Associated functions:

initializing a conversation in the current directory;
selecting a model or session options;
interacting with the sandbox and approvals;
displaying plans, diffs, and outputs;
resuming or delegating to subcommands.

9.2 `resume` subcommand

resume represents the session resumption function. It attaches a new execution to an existing transcript and preserves relevant context from the previous conversation.

Resume variants distinguish the latest session, a session selected from a list, a specific session by identifier, and, depending on the option, sessions outside the current directory.

9.3 `exec` subcommand

exec represents non-interactive execution. It processes an instruction provided at launch and produces output intended for scripts, integration pipelines, or reproducible tasks.

This function preserves Codex security constraints: sandboxing, approvals, configuration, project instructions, and tool limits.

9.4 Server subcommands

Server functions, including the app server and remote modes, expose a Codex session to a client connecting through a local channel or WebSocket. They provide separation between the service process and the interaction client.

Server functions include:

listening on a local or remote address;
authentication through a token or configured mechanism;
remote client connection;
control of a session from another surface.

9.5 Slash commands

Slash commands represent session actions available in interactive interfaces. They expose functions such as state display, model switching, context management, session exit, or access to help.

Exact availability varies across CLI, IDE, and App.

9.6 `AGENTS.md` file

AGENTS.md is a durable instruction file. It is read as project guidance and may exist at several levels: global user level, repository root, and subdirectories. Files closer to the working directory define the most specific guidance.

Functional attributes:

durable scope;
versionable with the repository when placed in the project;
priority by proximity;
adaptation of Codex behavior before work starts;
support for conventions, commands, and review expectations.

9.7 Configuration file

The Codex configuration file represents persistent client and agent settings. It may define default values for the model, permissions, sandbox, MCP servers, hooks, and execution preferences.

Effective settings result from combining global configuration, project configuration, launch options, managed policies, and interface choices.

9.8 Environment variables

Environment variables provide a configuration channel outside the configuration file. They are suitable for secrets, environment-specific paths, and settings injected by an execution pipeline.

An environment variable may be ignored or overridden if the surface, organization policy, or active configuration imposes another value.

9.9 Rules and hooks

Rules define allow or deny policies around commands and actions. Hooks provide execution points around Codex events.

Rules are declarative. Hooks are procedural. Both mechanisms complement user approvals and sandbox limits.

9.10 Permission profiles

Permission profiles represent sets of granted or denied capabilities: reading, writing, execution, network access, access to additional directories, or use of external tools.

Profiles may be defined locally, managed by an organization, or requested during a session.

10. Functional matrix

10.1 Features by surface

The Codex App covers parallel threads, worktrees, integrated terminal, Git diffs, artifacts, integrated browser, automations, notifications, and IDE synchronization.

The CLI covers terminal interaction, scriptable sessions, conversation resumption, non-interactive modes, launch options, and server or remote modes.

The IDE extension covers editor context, open files, selections, IDE commands, and iteration directly inside the development environment.

Codex Web and Cloud cover remote execution, configured environments, delegated tasks, and cloud integrations.

10.2 Features by task type

For code understanding, Codex uses file reading, structure analysis, synthesis, and explanation.

For code modification, Codex uses planning, editing, command execution, verification, and summary.

For review, Codex uses diff inspection and searches for bugs, risks, regressions, and missing tests.

For automation, Codex uses recurring prompts, project context, worktrees or local environments, skills, and notifications.

For external integration, Codex uses MCP, plugins, connectors, APIs, or cloud surfaces depending on configuration.

10.3 Relationships between mechanisms

AGENTS.md describes durable repository rules. Skills describe reusable workflows. Plugins package capabilities. MCP connects Codex to external systems. Hooks impose processing around events. Automations schedule execution.

These mechanisms are complementary: AGENTS.md guides behavior, skills describe how to perform workflows, MCP gives access to data or actions, hooks frame execution, and automations trigger work over time.

Sources

OpenAI Developers, Codex Overview, consulted June 12, 2026.
OpenAI Developers, Codex Quickstart, consulted June 12, 2026.
OpenAI Developers, Codex app features, consulted June 12, 2026.
OpenAI Developers, Codex CLI features, consulted June 12, 2026.
OpenAI Developers, Codex customization, consulted June 12, 2026.
OpenAI Developers, Codex documentation related to sandboxing, configuration, MCP, skills, and automation, consulted June 12, 2026.