OpenAI Codex - User Guide

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

Preface

This guide explains how to use OpenAI Codex to work on code, review changes, automate tasks, and use the App, CLI, IDE, and Web surfaces.

It assumes the user has an authorized account or API key and that Codex is available in their plan or organization.

Audience

This guide is intended for users who want to launch Codex, choose a surface, assign a task, review changes, and configure the main customization and security mechanisms.

Document structure

This guide contains the following chapters:

Chapter 1: getting started and choosing a surface.
Chapter 2: using the Codex App.
Chapter 3: using the CLI.
Chapter 4: using the IDE extension.
Chapter 5: using Codex Web and Cloud.
Chapter 6: guiding Codex.
Chapter 7: verifying and finalizing work.
Chapter 8: customizing Codex.
Chapter 9: permissions, sandboxing, and common troubleshooting.
Chapter 10: common scenarios.

Conventions

Commands are shown in monospace. Examples must be adapted to the project, shell, and local rules. Operations that modify files, execute commands, or access the network may require approval.

1. Getting started

1.1 Choose the surface to use

Use the Codex App when you want to manage several projects, handle threads in parallel, work with worktrees, inspect diffs, and use integrated desktop functions.

Use the CLI when you mainly work in a terminal or want to automate tasks.

Use the IDE extension when you want Codex to naturally see editor context and work close to the files you have open.

Use Codex Web or Cloud when you want to delegate work to a configured remote environment.

1.2 Prepare a project

Before starting a task:

Open the project folder.
Check the Git state.
Note important test or verification commands.
Clearly describe the expected result.
Specify limits: files not to touch, style to preserve, tests to run.

It is prudent to create a Git checkpoint before a task that may modify code.

1.3 Write a good request

An effective request includes the objective, useful context, constraints, affected files or areas, accepted risk level, and expected verification.

Example:

Find why the payment test fails and fix only the likely cause.
Read the payment test and service files first.
Keep changes minimal and run the relevant test.

2. Use the Codex App

2.1 Install and open

Install the Codex application for macOS or Windows from the official page. Open the application, then sign in with a ChatGPT account or an OpenAI API key.

Some functions may vary depending on authentication mode, plan, and organization policies.

2.2 Select a project

In the application, add or select the project folder. A project corresponds to a codebase or to a coherently bounded part of a codebase.

If a repository contains several independent applications, create separate projects to keep the work perimeter clear.

2.3 Choose the thread mode

When starting a thread, choose a mode:

Local: Codex works in the current folder.
Worktree: Codex creates a Git worktree to isolate changes.
Cloud: Codex works in a configured remote environment.

Choose Worktree to try an idea, run several tasks in parallel, or protect your current directory.

2.4 Send a first request

In the composer, describe the task. For a first contact with a project, ask for an analysis:

Explain the organization of this project and list useful commands for testing it.

For a targeted change:

Add the missing validation to the sign-up form.
Follow the existing style and run the relevant tests.

2.5 Follow the work

During execution, watch the proposed plan, files read, requested commands, produced changes, error messages, and approval requests. Redirect Codex if the work moves outside the intended scope.

2.6 Use the integrated terminal

Each thread has a terminal associated with the project or worktree. Use it to run verification commands:

git status
npm test
pnpm run lint

Codex can read terminal output when the surface allows it. You can therefore ask it to analyze a test failure that is already visible.

2.7 Review Git differences

Open the diff panel to see modified files. Check that the right files changed, that modifications are minimal, that tests or evidence are present, and that no sensitive data was added.

Add inline comments if you want Codex to correct a specific line or section.

2.8 Commit, push, and pull request

When changes are correct, use the integrated Git functions or the terminal to prepare the commit.

Before pushing:

Review the diff.
Run the required tests.
Check the commit message.
Create the pull request if the project workflow requires it.

2.9 Use the integrated browser

To verify a local web application:

Start the development server.
Open the page in the integrated browser.
Inspect the rendering.
Add comments on visual elements to correct.
Ask Codex to apply the corrections.

The integrated browser does not replace a browser connected to your profile. It is not intended for complex authentication flows.

2.10 Use images and artifacts

Drag an image into the prompt to provide it as context. For documents, spreadsheets, presentations, or PDFs, specify the expected file type, structure, verification criteria, and desired output path if needed.

3. Use the CLI

3.1 Start an interactive session

From the project directory:

codex

You can also provide an initial request:

codex "Explain this codebase"

Codex opens an interactive terminal interface that can read the repository, propose a plan, modify files, and run commands depending on authorizations.

3.2 Interact during a session

During a CLI session, send prompts and code excerpts, review plans and diffs, accept or refuse controlled operations, use available slash commands, and exit the session when the work is complete.

3.3 Resume a session

To reopen a recent session:

codex resume

To resume the latest session for the current directory:

codex resume --last

To also list sessions from other directories:

codex resume --all

Resumption preserves the transcript, plan history, and useful session context.

3.4 Launch with a specific model

When you need to explicitly choose a model:

codex --model gpt-5.5

Inside a session, use the model-switching command provided by the interface.

3.5 Run in non-interactive mode

For automated workflows, use non-interactive mode when available:

codex exec "Run the tests and summarize failures"

Non-interactive mode is suitable for bounded tasks. Provide a precise prompt and configure permissions before integrating it into an automated chain.

3.6 Use remote mode

An app server can expose a WebSocket connection. The CLI client can connect to it with a remote URL and configured authentication.

Use an unencrypted connection only for localhost or a trusted tunnel. For a remote machine, provide authentication and TLS according to official rules.

4. Use the IDE extension

4.1 Install the extension

Install the Codex extension in the supported editor. Then open the Codex panel from the sidebar.

Sign in with your ChatGPT account or an OpenAI API key. The extension starts in default agent mode when the configuration allows it.

4.3 Work with editor context

Open the relevant files before asking a question. You can ask:

Explain the open file and identify risky functions.

Or:

Fix the issue in the selected function without changing the public API.

4.4 Synchronize with the Codex App

When the Codex App and IDE extension are open on the same project, they can synchronize context and threads. Use this synchronization to move between editor work and broader review in the application.

5. Use Codex Web and Cloud

5.1 Choose a cloud task

Use Cloud for tasks that can run in a remote environment: repository analysis, isolated fixes, migration, test generation, review, or a long parallel task.

Avoid sending a cloud task when the result depends on an unpushed local file, a local secret, or a tool unavailable in the environment.

5.2 Configure the environment

Before assigning a cloud task, check repository access, dependencies, test commands, network access, authorized variables and secrets, and organization policies.

5.3 Retrieve results

Review the summary, modified files, logs, and tests run. Bring changes back into your Git workflow according to the project procedures.

6. Guide Codex

6.1 Give short, verifiable instructions

Prefer:

Add a test for the case where the amount is zero, then fix validation if the test fails.

Avoid overly broad requests without criteria:

Improve the whole module.

6.2 Frame changes

Clearly indicate authorized files, forbidden files, accepted refactoring level, required tests, and expected response format.

6.3 Request a review

For a code review:

Review this diff. Prioritize bugs, regressions, security risks, and missing tests.
Do not modify files.

6.4 Request a careful fix

For a fix:

Find the most likely cause of the failure and fix it with the smallest reasonable change.
Explain the modified files and tests run.

6.5 Provide expected evidence

Add the desired verification:

Run the relevant unit test and report the exact result.
If the test cannot be run, explain why.

7. Verify and finalize

7.1 Read the summary

At the end of a task, check that the summary answers the initial request: objective reached, modified files, tests run, limitations, and possible next steps.

7.2 Check the diff

Before validating:

git status
git diff

Make sure no unrelated file was modified.

7.3 Run tests

Run the tests recommended by Codex or by the project:

npm test
pnpm test
pytest
cargo test

Adapt these commands to your stack.

7.4 Request a second pass

If a detail is missing:

The change is good, but add a test for edge case X and rerun only that test.

If the result is too broad:

Return to a more minimal fix. Keep only the changes necessary for the reported bug.

8. Customize Codex

8.1 Add an AGENTS.md file

In the repository, create an AGENTS.md file for durable rules:

# Instructions for Codex

- Use pnpm, not npm.
- Run `pnpm test` before proposing a commit.
- Do not modify generated files in `dist/`.
- For React components, follow the patterns in `src/components`.

Place a more specific AGENTS.md in a subdirectory if different rules apply to that area.

8.2 Update AGENTS.md after a recurring error

If Codex repeats a wrong assumption, ask it to formalize the correction:

Add to AGENTS.md that database migrations must be created with the internal tool, not by hand.

8.3 Use a skill

Use a skill when a workflow recurs often: release, review, documentation generation, data verification, or artifact creation.

You can explicitly invoke a skill if its name is known:

$skill_name Prepare the release note from the current diff.

8.4 Configure MCP

Use MCP when Codex must access external tools or data: tickets, internal docs, knowledge bases, repositories, design services, or other team systems.

In the Codex App, open the MCP section of settings to enable a recommended server or add a configuration.

8.5 Use hooks

Use hooks to automate checks around Codex actions, for example verifying a policy before a command or logging certain events.

8.6 Use automations

To create a recurring task, describe the frequency, project, request, expected result, and notification or summary channel.

Example:

Create a daily automation that checks recent test failures and produces a short report.

Use a thread automation when the recurrence must preserve the context of the current conversation.

9. Permissions, sandboxing, and troubleshooting

9.1 Understand approvals

When Codex asks for approval, read the requested action, affected files or resources, authorization duration, and risk level.

If you hesitate, grant the narrowest scope or refuse and ask for another approach.

9.2 Understand the sandbox

The sandbox limits Codex access. If a command fails because of insufficient access, choose between granting targeted permission, moving required files into the project, asking for a solution that does not need that access, or opening a more appropriate project.

9.3 Manage network access

If Codex must verify recent information or install a dependency, it may need network access. Grant access only if the task justifies it and the project policy allows it.

9.4 When Codex does not find the right files

Give a routing hint:

Read `src/payments/` and `tests/payments/` first. Ignore `legacy/` unless necessary.

If this hint will be useful long term, add it to AGENTS.md.

9.5 When Codex proposes too many changes

Rephrase with an explicit constraint:

Reduce the change to the minimum necessary. No refactoring outside the affected file.

9.6 When tests fail

Ask for a bounded analysis:

Analyze this test failure. Do not modify anything before identifying the likely cause.

Then, if the cause is clear:

Apply the minimal fix and rerun this test only.

9.7 When to use another surface

Move to the IDE if the main context is an open file or selection. Move to the Codex App if you need to manage threads, worktrees, diffs, and artifacts. Move to the CLI if the work is terminal-first or scriptable. Move to Cloud if the task must be delegated remotely.

10. Common scenarios

10.1 Understand an unfamiliar codebase

First ask for a map before any modification:

Explain the organization of this project. Identify the main modules, verification commands, and files to read before modifying code.
Do not modify anything.

If the project is large, bound the search:

Focus on the authentication flow. Read relevant files and summarize the end-to-end flow.

When the synthesis is correct, ask Codex to propose durable guidance:

Propose a short AGENTS.md section to help future sessions find the right authentication files.

10.2 Fix a low-risk bug

Start with reproduction:

Reproduce or locate the reported failure. Do not fix anything before identifying the likely cause and affected files.

Then ask for the fix:

Apply the minimal fix for this likely cause. Avoid any unnecessary refactoring. Run the most targeted test.

Finish with verification:

Summarize the change, the test run, and remaining risks.

10.3 Add a small feature

Provide the definition of done:

Add the "archives" filter to the folder list.
The filter must be visible in the interface, persist in the URL, and be covered by a test.
Follow existing patterns.

If Codex proposes an architecture that is too broad:

Keep the implementation local to this module. Do not create a new abstraction unless it already exists in the project.

10.4 Review a pull request

In a surface that can see the diff, ask:

Review this diff as a senior reviewer.
List likely bugs or regressions first, with file and line.
Then mention missing tests.
Do not comment on style unless it hides a risk.

To turn the review into fixes:

Fix only the P1 and P2 review points. Leave the rest untouched.

10.5 Work on a web interface

Start the local server, then ask Codex to verify:

Open the local application in the integrated browser, check the login page, and fix visible layout issues.
Test desktop and mobile if possible.

Add comments in the integrated browser if a specific visual element must be corrected, then ask:

Process the browser comments and verify the rendering again.

10.6 Produce a document or artifact

Give the expected form:

Create a Markdown reference document for this module.
Structure: preface, audience, concepts, API, errors, examples.
Document only behavior present in the code.

For an office artifact:

Create an 8-slide presentation from these notes.
Add a summary slide, a risks slide, and a next steps slide.
Verify the rendering before giving me the file.

10.7 Set up an automation

Describe the recurrence and expected result:

Create a weekly automation for this project.
Every Monday morning, it must check outdated dependencies, summarize important updates, and not modify any files.

For follow-up in the same thread:

Add a thread automation that reminds me every 30 minutes until the deployment is complete.

10.8 Add an external integration

When information lives outside the repository, prefer MCP or a plugin:

Configure or use the appropriate connector to read the Linear ticket linked to this branch, then summarize the acceptance criteria.

If the tool is not available:

Indicate which integration is missing, which permissions would be required, and what information I can provide manually.

10.9 Clean up after a task

Before closing:

Check Git state, list modified files, and indicate the test commands run.
Flag any file unrelated to the task.

If changes must be separated:

Propose a logical commit split. Do not stage anything without confirmation.

10.10 Write a durable instruction

After several course corrections, ask:

Turn my recurring corrections into short AGENTS.md instructions, without duplicating what already exists.

Review the proposal before accepting it. Durable instructions should remain small, specific, and useful to future sessions.

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.