Your First Codex Task

Updated November 3, 2026 based on the Codex command reference (CLI 0.166.0): the --show-diff and --apply options do not exist. Locally, Codex modifies files directly within its sandbox; review changes using /diff or git diff. The “Codex: New Task” extension command has been replaced by Codex: Open Codex Sidebar. Sources: Developer commands · Codex IDE extension.

Launch Your First Task

Your account is set up, GitHub is connected, and AGENTS.md is in place: it’s time to see the agent in action. Here is a rule of thumb for every skill level—start with a task where you already know the correct answer. You won’t learn much watching Codex solve a problem you can’t evaluate, but you will learn a tremendous amount by watching it operate on familiar ground.

From Codex Cloud

On the web or in the desktop app, choose Work in › Cloud, select the published environment for your repository (Lesson 2), and type your task into the input field. Something deliberately modest works perfectly well.

Task: "Add a .gitignore file suitable for a Node.js/TypeScript 
       project if one doesn't already exist."

This phrasing includes a condition—“if one doesn’t already exist”—which is exactly what makes it interesting to observe. In Codex Cloud, the task runs in the environment you published for this repository: Codex checks whether a .gitignore exists, verifies that it covers Node.js and TypeScript if it does, creates or updates the file as needed, and then shows you the result as a diff. The execution log streams in real time: this is where you’ll see whether the agent respected the condition or overwrote your existing file.

From the IDE

Open your project in VS Code (or Cursor, Windsurf) and launch Codex via its icon or the Command Palette:

Ctrl+Shift+P → "Codex: Open Codex Sidebar"

Then formulate a request that leverages local context by naming the specific file:

"Add email validation to the contact form 
 in src/components/ContactForm.tsx"

The extension displays a summary and the modified lines alongside the code; you keep the changes you want and ask for follow-ups within the same conversation. The documentation recommends creating a Git checkpoint before and after the task so you can roll back if needed.

From the CLI

# Navigate to the project directory
cd my-project

# Start a session with an initial instruction
codex "Add a README.md with the project description, installation instructions, and available commands"

Locally, Codex modifies files directly in your working directory, within the limits of the sandbox and approval policy: it asks for permission before taking actions that require it. To review what changed before committing, type /diff in the session: the command displays the Git diff, including untracked files. /review asks Codex to review your working tree itself. For scripted usage, codex exec runs the same task without interaction (Lesson 14)—in that case, it’s up to Git and your pipeline to decide what gets kept.

Anatomy of a Codex Result

Regardless of the entry point, a completed task always returns the same four elements. Review them in this order: the diff says what changed, the log says why, the tests say if it’s safe, and the actions hand control back to you.

Beginners often neglect the execution log, yet it’s the element that teaches you how to formulate your tasks. By seeing which files Codex opened before making a decision, you discover what it was looking for but couldn’t find—often a convention that should have been in AGENTS.md.

Writing Good Instructions

Result quality depends directly on instruction quality, and the gap between the two formulations below is far larger than the gap between two models.

"Improve the code"

"In src/lib/auth.ts, replace manual JWT handling 
with the jose library. Keep the same public interface 
(signToken, verifyToken). Update the corresponding tests."

The second version works because it answers four questions the agent asks itself anyway. It specifies the files involved, saving it from exploring and targeting the wrong location. It defines the expected outcome—behavior, interface, format—so it knows when to stop. It sets constraints, here preserving the public interface, which prevents it from “improving” things by breaking callers; elsewhere this might be “do not break tests.” And when the stakes justify it, it adds business context: specifying “this is a payment form, security is critical” genuinely changes its trade-offs.

To make this your own, take an existing project and chain together three tasks of different natures: an analysis without modification, “List all TypeScript files that lack associated tests”; a targeted generation, “Generate a unit test for this file”; a limited-scope fix, “Fix ESLint warnings in src/utils/”. For each, note what you should have specified upfront: this list of regrets is your first draft of AGENTS.md.

Key Takeaways

• Launch your first tasks with simple, targeted requests
• Codex provides a complete execution log for every task
• Result quality depends on the precision of your instructions
• You always retain control: approve, modify, or reject
• Start with low-risk tasks before moving to critical changes