Codex App: projects, threads, worktrees, plugins, automations

What to understand

• Codex is one agent behind six surfaces, not six products. The same model, account context, and approval/sandbox concepts show up in the desktop App, the IDE extension (VS Code, Cursor, Windsurf, and JetBrains IDEs), the open-source CLI, the Cloud/Web surface at chatgpt.com/codex, the GitHub integration (@codex on issues and PRs), and the Chrome extension. Learning the App teaches you most of what transfers everywhere else, the differences are about WHERE the work runs, not a different agent.
• The desktop App is a focused workspace for running Codex threads in parallel, with built-in Git worktree support, an integrated terminal, an in-app browser, a Review pane, an Artifacts panel, automations, and plugins/MCP. It runs natively on macOS (Apple Silicon and Intel) and Windows (PowerShell + native sandbox); Linux is on a waitlist as of June 2026.
• A 'project' is simply a folder you grant Codex access to, usually a Git repository, but it can be any working directory. Projects live in the left sidebar so you can keep several open and switch between them; the folder name is how the App labels the project.
• A 'thread' is a single conversation-plus-task against a project. Because the App is built for multitasking, you run several threads side-by-side, each doing independent work, instead of waiting for one to finish before starting the next. Parallelism is the App's core advantage over a single chat window.
• Worktrees use Git's native worktree feature so parallel threads never collide. Each thread can operate on its own checkout, so unfinished or experimental work in one thread cannot contaminate another thread or your main branch, and a failed experiment is discarded by deleting the worktree, not by unpicking commits on main.
• The Review pane is where safety lives on the local surfaces: you inspect diffs line-by-line, address PR feedback, stage individual files, write a commit message, and commit and push from inside the App. Codex proposes; you remain the gate that decides what enters your repository.
• Supporting panels make the App a self-contained cockpit: the integrated terminal runs commands per thread and can launch repeatable project actions; the in-app browser renders local dev servers and lets Codex operate local browser flows; the Artifacts panel surfaces plans, sources, task summaries, and generated-file previews; and Appshots send your frontmost macOS window to Codex as a screenshot for visual context.
• Sandbox and approval settings are two independent dials that govern a thread's autonomy. The sandbox decides WHAT a thread can technically do (read-only, workspace-write, or danger-full-access); the approval policy decides WHEN it must ask you before escalating. These settings carry through to worktrees, automations, and the App's IDE-extension integration, so set a conservative default once and let it propagate.
• Cloud delegation is the App's force multiplier. From the App, the IDE, or chatgpt.com/codex you can hand a longer or independent job to a cloud environment that runs in OpenAI's infrastructure, then come back to review the diff or open a pull request, your machine stays free and you can fire off several cloud tasks in parallel. The local surfaces (App/IDE/CLI) and the cloud surface share the same agent; the choice is about where the compute and the working copy live.
• Cloud tasks run inside an 'environment' you configure per repository: the container image, setup scripts that install dependencies and tools (linters, formatters), environment variables, and crucially the internet-access policy. The environment is the reproducible box your delegated task runs in, get it right once and every cloud task on that repo inherits it.
• Agent internet access is OFF by default during the agent phase, on purpose. Setup scripts still run with internet so you can install dependencies, but the agent itself cannot reach the public internet unless you opt in, and when you do, you choose between an empty allowlist, a 'common dependencies' preset, or unrestricted, optionally capped to safe HTTP methods (GET/HEAD/OPTIONS). This default is your main defence against prompt-injection and secret exfiltration.
• GitHub and Chrome are the two 'reach beyond the repo' surfaces. The GitHub integration lets you kick off work or request a review by mentioning @codex on an issue or PR, and can auto-review every new PR (flagging only P0/P1 issues, guided by your AGENTS.md review guidelines). The Chrome extension lets Codex act inside your signed-in browser session, across task-specific tab groups, in parallel, without taking over your active browsing, for work that genuinely needs authenticated web state.
• Automations and plugins turn the App from a tool into a system. Automations schedule recurring tasks or wake the same thread for ongoing checks; plugins are installable bundles that combine skills, integrations, and MCP server configuration into reusable workflows (for example a Sites plugin to create, deploy, and inspect websites). Both inherit the same sandbox/approval guardrails, automation does not mean un-gated.

Deeper dive

Codex surfaces compared, where each kind of work belongs

The six front doors to the same Codex agent, what each is best at, where the code actually runs, and the default safety posture. Use this as a routing table: pick the surface by where the work should execute, not by habit. Codex ships rapidly, feature names and defaults change; verify at developers.openai.com/codex before relying on specifics.

Sources (as of June 2026): Codex. App · Codex. IDE extension · Codex. CLI · Codex. Web/Cloud · Codex. Code review in GitHub · Codex. Chrome extension

Step by step

1

Install the App and sign in

12

Download the Codex App from the official Codex app page (the page shown), macOS (Apple Silicon/Intel) or Windows build. Launch it and sign in with your ChatGPT credentials for subscription billing, or paste an OpenAI API key if you prefer metered key-based usage. Note your model options (e.g. the GPT-5.x-codex family) but don't change anything yet. You're done when the App opens, your account shows in Settings, and the composer's model picker lists the GPT-5.x-codex family.

HintSign in with the same ChatGPT account you'll use on mobile, that's what later (Lesson 11) lets you steer a Mac host from your phone via Remote Connections.

On this screen

1. 1Getting-started checklist. The docs page's numbered steps, download, sign in, select a project, send a message, are exactly steps 1, 2 and 4 of this lesson.
2. 2Download buttons. Pick your platform here. The Linux desktop App is waitlisted as of June 2026, the CLI and IDE extension already run on Linux.

2

Add a Git-backed project

12

From the project sidebar on the left, add a project and select a folder on your machine. Codex now treats that folder as a project you can open threads against; its name appears in the sidebar. Choose a folder that is already under Git, this is the prerequisite that unlocks worktrees, clean diffs, and a working Review pane.

HintIf `git status` doesn't run cleanly in the folder, fix that first. A non-Git folder gives you a degraded App with no isolation and nothing to stage.

On this screen

1. 1Project sidebar. Holds every folder you've granted access to; click a project to make it active. Keep several open and switch between them.
2. 2Branch control (bottom right). The main branch selector in the composer bar confirms the folder is Git-backed, no Git, no worktrees, no clean diffs, nothing to stage in Review.

3

Set a conservative sandbox and confirm the approval policy

Before sending any message, open the thread's settings and set two independent dials: the SANDBOX (what it can do, choose read-only or workspace-write for a first run, not danger-full-access) and the APPROVAL policy (when it must ask, keep it on-request so it asks before escalating). Remember these propagate to worktrees and automations, so the default you set here travels. You'll know it took when the permissions control in the thread composer shows your chosen mode instead of Default permissions.

HintSandbox = capability (read-only / workspace-write / danger-full-access); approval = friction (when it stops to ask). Lesson 1 introduced the dials; here you set them for real, start tight on both, loosen deliberately per task.

4

Start a thread and watch the Artifacts panel

12

With the project active, type a small plain-language task into the active thread, e.g. 'summarise this repository's structure and the entry points' or 'draft a one-line change to the README'. Watch the Artifacts panel populate with its plan, sources, and any file previews as it works. Keep this first task read-only-ish and verifiable: you're testing the loop, not shipping a feature. Success looks like this screenshot, a transcript of commands and reasoning ending in a small change summary you have not yet approved.

HintRead the plan in Artifacts before you approve any edit, it's the cheapest place to catch a misunderstanding, exactly the read-only-first habit from Lesson 1.

On this screen

1. 1Active thread workspace. Where you converse with Codex and watch it reason and act, one thread among several you can run in parallel.
2. 2Change summary card. The '1 file changed +1 -9' card with Undo is the App surfacing proposed work for review, the same +/- numbers appear beside the thread in the sidebar.

5

Isolate a change on its own worktree

For any change you're not certain about, run the thread on its own Git worktree so its edits live on a separate checkout. This keeps experimental work isolated from your main branch and from other threads running in parallel. Now start a SECOND thread on the same project to prove parallelism, the two cannot see each other's uncommitted changes. Proof of isolation: ask the second thread to read the file the first thread edited, it sees the committed version, not the uncommitted change.

HintTreat a worktree as a disposable sandbox branch: if the experiment fails you delete the worktree and main is untouched, no revert, no force-push, no cleanup. A worktree is a real separate checkout sharing the repo's history, deleting it discards the experiment cleanly.

6

Review, stage, and commit, you are the gate

Open the Review pane to inspect the diff line-by-line. Stage only the files you approve, write a commit message, then commit and push from inside the App. Nothing reaches your remote until you take this step, treat it like a pull-request review of your own work. When the commit lands, the Review pane empties and the thread's +/- counters reset.

HintIf the diff includes anything outside the stated scope (reformatted lines, touched config), don't stage it, un-scoped changes are the #1 sign the prompt was too loose. Stage individual files, not all-or-nothing, the Review pane is your final human gate before code leaves your machine.

7

Decide local vs cloud for your NEXT task

Pick a second, real task and route it deliberately using the surface comparison table and the cloud-vs-local deep dive. If it's tight and interactive, keep it in an App/IDE/CLI thread. If it's long or independent, set up (or reuse) a cloud environment: confirm internet access is OFF by default, define setup scripts for dependencies, and only then delegate. Write down WHY you chose that surface, that reasoning is the skill. If you route to the cloud, carry the two posture facts with you: agent internet is OFF by default (enable narrowly, allowlist plus safe HTTP methods, only if truly needed), and the environment, image, setup scripts, env vars, internet policy, is configured once per repo and inherited by every cloud task on it.

HintThe contractor test: if you could hand the task to a competent stranger with only the repo and a written brief, it's a cloud task; if you'd need to be in the room pointing, keep it local.

8

Find Automations, Skills and Plugins, then park them

12

Locate Automations and Skills at the top of the App sidebar (you saw them in step 2's screenshot), then open the plugin directory shown here and read what a plugin bundles, skills, app integrations, and MCP server config in one installable package. Install nothing yet. You're done when you can point at where automations and plugins live and say what each is for.

HintAutomations get a full lesson of their own (Lesson 12), today's job is only to know where the doors are. Treat installing a plugin as a trust decision, not a click.

On this screen

1. 1Plugin directory. Plugins are curated by OpenAI, shared from your workspace, or created by you, read what one bundles before installing.
2. 2What a plugin extends. Skills, integrations, and MCP servers combined into a reusable workflow, e.g. a Sites plugin to create, deploy, and inspect websites.

Production prompt examples

ROLE: You are a senior engineer running this as an autonomous CLOUD task against a fresh checkout of the repo. I am NOT watching live, assume you must finish and produce a reviewable PR with no further questions unless you are truly blocked.

CONTEXT:
- Repo: this environment's default branch.
- The environment's setup script has already installed dependencies. Do NOT change tooling, lockfiles, or CI config.
- Agent internet access is OFF for this task. If you believe you need a network call, STOP and report it in the PR description instead of attempting it.

GOAL (single, verifiable):
Migrate every call site of the deprecated `getUserById(id)` helper to the new `users.findById(id)` API, then delete the deprecated helper. Behaviour must not change.

SCOPE / GUARDRAILS:
- In scope: src/** call sites and the helper's own file. Out of scope: tests' intent (you may update test imports, not test assertions), public API shape, formatting of unrelated lines.
- Make the smallest diff that achieves the goal. Do not opportunistically refactor or reformat untouched code.
- Keep each logical change reviewable; do not squash unrelated edits together.

DEFINITION OF DONE (you must verify before opening the PR):
1. `getUserById` no longer exists in the codebase (grep returns nothing).
2. The project builds and the existing test suite passes locally in the environment.
3. No new dependencies, no network calls, no changes outside the stated scope.

OUTPUT:
Open a pull request with: a one-paragraph summary of what changed and why, the exact verification commands you ran and their results, and an explicit 'Risks / things to double-check' list for the human reviewer. If you hit a blocker, open the PR as a draft and put the blocker at the top of the description.

Common mistakes to avoid

• Pointing Codex at a folder with no Git history, then wondering why worktrees, clean diffs, and the Review pane don't work. Git is the prerequisite, not an optional extra.
• Treating the App as the whole of Codex and never learning the other surfaces, so long independent jobs tie up your machine instead of running in the cloud, and browser tasks get hacked together instead of using the Chrome extension.
• Leaving the sandbox on danger-full-access (or the IDE on 'Agent (Full Access)') for a first run instead of starting read-only or workspace-write with on-request approvals.
• Committing straight from a thread without opening the Review pane, so un-scoped changes (reformatted lines, touched config) slip into the repo.
• Running everything in one thread instead of using parallel threads and worktrees to keep experiments isolated and disposable.
• Enabling unrestricted agent internet on a cloud task 'to be safe', inverting the actual safety default, internet is OFF for a reason; turn it on narrowly, with an allowlist and safe HTTP methods, only when the task needs it.
• Delegating a trivial tweak to a cloud environment (where setup cost dwarfs the task) or grinding a huge independent refactor locally (blocking your machine and losing parallelism), the local-vs-cloud choice is a real cost decision.

Source conflicts to review

• Surface naming drifts across OpenAI's own docs and third-party guides: the cloud surface is labelled 'Web' in the App nav but documented under /codex/cloud, and the Chrome integration is sometimes called a 'plugin'. Names here are accurate as of June 2026, re-verify and distrust tutorials more than a few weeks old.
• Autonomy controls use different vocabulary per surface (IDE: Chat / Agent / Agent (Full Access); CLI & App sandbox: read-only / workspace-write / danger-full-access) for the same underlying idea, don't assume a setting name on one surface exists verbatim on another.
• Capabilities are moving fast (computer use, Goal mode, Appshots, the Chrome extension, the Sites plugin and auto-review all shipped between March and June 2026). A given feature may have changed defaults or names since this snapshot, confirm on the changelog at developers.openai.com/codex/changelog.
• Desktop App Linux support is waitlisted as of June 2026 while the CLI and IDE extension already run on Linux; some write-ups blur 'App availability' with 'Codex availability'.