Run your first Codex task

A first Codex task runs an open-ended prompt across all four surfaces: the ChatGPT desktop app, the CLI, the IDE extension, and Cloud environments. Each surface follows the same cycle of exploration, analysis, implementation, and testing, powered by models such as GPT-5.6 Sol and GPT-6 Astra, while differing in how progress renders, how approvals gate tool execution, and how code diffs are reviewed.

This guide is for developers executing their first multi-file task with OpenAI Codex. You will discover error handling gaps, implement fixes, run tests, and evaluate surface-specific features. For team-wide lifecycle integration, see Build.

First task outcomes

Complete an end-to-end task spanning prompt input, sandboxed execution, and diff review.
Run the identical prompt across the Desktop App, CLI, IDE extension, and Cloud environments.
Understand how approval policies, git worktrees, and sandbox boundaries shape execution.
Deploy reusable prompt templates for error hunting, refactoring, and feature additions.

Task definition

This walkthrough uses a real-world task required in every production project: locate an error handling gap in your API routes, implement a fix, and verify it with a dedicated automated test. This exercise tests repository reading, AST analysis, code generation, sandboxed command execution, and git status tracking.

Use the following prompt:

Find an error handling gap in this project's API routes: a place where an
exception could crash the server or return a misleading response. Fix it with
proper error handling and add a test that proves the fix works. Run the tests
to confirm they pass.

The prompt is deliberately outcome-oriented. Codex must explore your codebase, identify a concrete issue, implement the fix, and validate execution. If your project lacks API routes, adjust the prompt to target your business logic layer.

Execute the task across surfaces

Desktop app workflow

To execute the task in the desktop application:

Open the ChatGPT desktop app in Codex mode and select your project directory.
Click New Thread. Select Worktree to isolate changes in a dedicated git worktree, or Local to modify your working directory directly.
Paste the prompt into the composer and press Enter.
Monitor execution. The app streams real-time status updates showing file reads, AST analysis, file edits, and test command execution. With workspace-write and on-request approvals, modifications within the workspace execute automatically without manual confirmations.
When execution completes, open the Review pane to inspect the file diff.
Use the integrated terminal (Cmd+J) to verify test output and inspect generated files.

Desktop app capabilities:

Parallel threads: Launch concurrent threads across independent worktrees without branch collisions.
Worktree isolation: Changes remain in a isolated git worktree, leaving your primary branch clean.
Voice input: Hold Ctrl+M to dictate prompts directly.
Completion notifications: System alerts notify you when background operations finish.

Terminal CLI workflow

To execute the task in the terminal:

Navigate to your project directory.

Launch the Codex interactive terminal interface:

codex --sandbox workspace-write --ask-for-approval on-request

Paste the task prompt and press Enter.
Observe streaming execution. Codex reads files, analyzes dependencies, generates code, and executes test runners within the workspace sandbox.
Run /review to invoke an automated code review pass on the staged diff:
Terminal window
```
/review
```
Inspect the Git diff:
Terminal window
```
git diff
```

CLI capabilities:

Mid-session model switching: Use /model to switch between GPT-5.6 Sol, Terra, or GPT-6 Astra during a task.
Checkpoint navigation: Press Esc twice in an empty composer to step backward through the transcript, then press Enter to branch from that point.
Headless scripting: Run tasks non-interactively using codex exec.
Multimodal input: Drag and drop screenshot files directly into the terminal window.

IDE extension workflow

To execute the task within your editor:

Open your project in VS Code, Cursor, or Windsurf.
Open the Codex sidebar panel.
Select Agent mode to grant file reading, code generation, and terminal execution permissions.
Paste the prompt into the editor sidebar and send.
Watch inline edits and terminal runs occur directly within your editor workspace.
Review proposed modifications using your editor’s built-in Git diff viewer.

IDE extension capabilities:

@file references: Type @src/routes/auth.ts to attach explicit file context directly to your prompt.
Context synchronization: The extension synchronizes open editor tabs with the desktop app context.
Cloud offload: Click the Cloud icon to dispatch execution to a remote container while keeping your local editor free.

Cloud environment workflow

To execute the task in a cloud container:

Navigate to chatgpt.com/codex.
Select your connected repository.
Click New Task and paste the task prompt.
Codex provisions a cloud container, clones the repository, installs dependencies, and executes the prompt.
Monitor execution logs in real time or close the browser session.
When the task completes, review the diff in the web interface.
Click Create PR to open a pull request, or check out the branch locally:
Terminal window
```
git fetch && git checkout BRANCH_NAME
```
Replace BRANCH_NAME with the branch generated by Codex Cloud.

Cloud environment capabilities:

Unattended execution: Operations run on remote cloud infrastructure without consuming local system resources.
GitHub issue integration: Trigger tasks directly by commenting @codex on an issue or pull request.
Automated PR packaging: Tasks generate pull requests complete with descriptions and test summaries.

Lifecycle stages in execution

Across all surfaces, Codex executes tasks in five structured stages:

Exploration: Codex inspects repository structure, reads configuration files, and maps code dependencies.
Analysis: It searches for missing error boundaries, evaluating exception handlers against framework standards.
Implementation: Codex edits files, adding input validation, try-catch blocks, or custom error wrappers.
Testing: It creates or updates test specifications and executes the test runner in the sandbox.
Summary: Codex outputs a summary detailing the identified gap, modified files, and test results.

The precision of execution depends on your repository’s AGENTS.md file. Documenting your package manager, test runner command (pnpm vitest run), and architectural boundaries prevents the model from relying on assumptions.

Reusable prompt patterns

Use the following templates for common development workflows:

Prompt for bug detection and remediation:

Scan this codebase for potential null pointer exceptions, unhandled promise rejections,
or missing error boundaries. Focus on the most critical user-facing code paths. Fix
the top 3 issues you find and add tests for each fix.

Prompt for modular refactoring:

The authentication middleware in src/middleware/auth.ts has grown to 200+ lines.
Refactor it into smaller, testable functions. Each function must have a single
responsibility. Update existing tests to match the new structure and add tests
for any previously untested paths.

Prompt for feature implementation:

Add rate limiting to the POST /api/login endpoint. Use a sliding window algorithm
with a limit of 5 attempts per minute per IP address. Return a 429 response with
a Retry-After header when the limit is exceeded. Add integration tests that verify
both the happy path and the rate-limited path.

Select the surface for your task

The following table summarizes recommended surfaces by task type:

Task type	Recommended surface	Rationale
Quick bug fix in one file	CLI or IDE Extension	Minimal context switching and fast turnaround.
Multi-file refactor	Desktop App (Worktree mode)	Clean branch isolation and parallel session support.
Long-running migration	Cloud environments	Background execution on independent compute.
Pull request automation	Cloud + GitHub connector	Direct PR generation and automated summaries.
Interactive debugging	CLI (interactive TUI)	Rapid turn rollback via `Esc` and checkpoint forks.
Visual UI development	IDE Extension	Instant inline diffs and visual inspection.

Troubleshoot execution issues

Codex modifies incorrect files: Specify explicit file boundaries in your repository AGENTS.md (for example, “API routes live in src/routes/, not src/api/”).
Tests fail after code modifications: Verify that AGENTS.md contains the exact test runner invocation (for example, npm run test:unit).
Codex enters a repetitive loop: Press Esc in the CLI or stop the thread in the Desktop App. Re-issue the prompt with tighter constraints.
Cloud task execution is slow: Optimize repository setup scripts to ensure dependencies are cached between task runs.
Approval dialogs interrupt unattended tasks: Use codex --sandbox workspace-write --ask-for-approval on-request to allow operations inside the repository to proceed automatically while guarding system boundaries.

Confirm that the task succeeded

To verify that the task completed successfully:

Inspect modified and created files:
Terminal window
```
git status -s
```
Confirm that only intended files were modified.
Run the newly created test:
Terminal window
```
npm test
```
Confirm that all test suites pass.
Verify repository formatting and types:
Terminal window
```
npm run typecheck && npm run lint
```
Confirm zero errors or formatting deviations.

Next steps

AI-Native SDLC: Stage 1 - Intent & Discovery Learn how to capture intent.md using Codex /plan and interactive discovery

AI-Native SDLC: Stage 3 - Build & Execution Master worktree isolation, sandbox policies, and headless execution with Codex

Review Agent Work Learn to review, refine, and merge Codex's changes using the review pane