Start From Zero and Choose the Right Surface

Codex can do more than generate an answer. Depending on the surface and permissions, it can inspect files, run commands, edit a project, search documentation, use connected services, operate a browser, and prepare reviewable artifacts. The practical consequence is simple: your request can affect a real environment. Supervise it like a capable teammate whose authority and finish line must be stated.

The durable mental model is an agent loop. Codex receives an objective, gathers relevant context, chooses an action, observes the result, and continues until it reaches a stopping condition or needs help. Buttons, mode names, and menu locations may change. The loop, the environment boundary, the permission boundary, and the need for verification are the concepts to learn for the long term.

Use the desktop app when the work benefits from a project view, longer collaboration, files, visual artifacts, browser verification, or other connected capabilities. Use the CLI when the terminal and local repository are the center of the job. Use the IDE extension when active editor context and tight code review matter. Use cloud tasks when work should run in an isolated hosted environment or continue away from the local machine.

These are not four intelligence levels. They are four operating contexts. A task can be well executed on the wrong surface and still fail your goal because it touched the wrong copy, could not see a local dependency, or produced a cloud result that was never integrated. Choose based on location, tools, duration, review, and side effects rather than habit.

A terminal shows a prompt, accepts a command, and prints output. The prompt usually includes the current folder; it is not part of the command you copy. Standard output is the normal result. Standard error contains warnings or failures. The exit status is a number programs use to report success: zero normally means success, while a non-zero value means the command failed or only partially completed.

Run one command at a time while learning. Read its output before continuing. `pwd` answers where you are, `ls` shows nearby files, `cd folder-name` moves into a folder, and `git status --short` shows changed files. If the terminal says `command not found`, the program is not installed or not on your PATH. If it says `not a git repository`, you are in the wrong folder or have not initialized Git yet.

You do not need an existing application. Create a new folder, enter it, initialize Git, and add one README file. Git gives Codex a safer project boundary and gives you a history you can inspect or restore. Then launch `codex` from that folder and ask for one static page using only `index.html`, `styles.css`, and `script.js`. This avoids package managers, accounts, databases, and deployment while you learn the edit-review-run loop.

If a repository already exists online, clone it instead. `git clone` downloads a working copy, and `cd` moves into it. Before launching Codex, run `git status --short` and read the repository's README. In the desktop app, add or open the same project folder. In VS Code, Cursor, or Windsurf, open the folder and choose the Codex sidebar; the IDE extension can then use open files and selections as context.

Treat an error as evidence. Copy the command, full error, current folder from `pwd`, and versions from `git --version` and `codex --version`. A missing `codex` command is an installation or PATH problem. An authentication prompt means the client needs sign-in. A Git error means either the folder is not a repository or Git is not installed. A dependency error in an existing app belongs to that project's documented setup, not to Codex itself.

Do not respond to setup friction by granting full access or pasting a credential into chat. First use `codex --help`, the official CLI page, and the repository's install instructions. If a command partly changed files, inspect `git status --short` before retrying. Preserve the failed output: it is the shortest path to a precise diagnosis.

Before asking Codex to change anything, identify the project, repository, checkout, branch, and existing uncommitted changes. A checkout is one working copy of a repository. A branch is a named line of change history. Uncommitted changes are edits on disk that Git has not recorded. You do not need to master Git yet, but you must know whether another person's work is already present.

Also name the proof layer. Source proof means the intended code exists. Local-runtime proof means a process built from that source behaves correctly. Preview proof means a shareable temporary environment serves the result. Production proof means the real public or internal service is running that release. Never use one layer as shorthand for another.

Start by asking Codex what the project does, where it starts, how it is tested, and which instructions govern work. Require paths or command output for the answer. This creates the habit of distinguishing evidence from plausible explanation before any source is touched.

Your first change should be narrow and easy to undo: correct one visible sentence, add one missing validation message, or adjust one small test fixture. Ask Codex to identify the intended files and verification step first. Then review the diff, run the check, and observe the result in the interface that matters.

Product interfaces change faster than engineering principles. A guide that says only which button to press will become stale. When a current label is useful, pair it with the durable job it performs: choose an environment, restrict authority, attach context, review a change, or collect proof.

Every chapter in this guide links to the current first-party documentation for exact UI and command details. If a screenshot and the live product disagree, follow the official current page and preserve the chapter's underlying decision. That is how a practical guide stays useful while the product improves.