ChatGPT · Codex on GitHub and in the IDE
You can hand Codex a GitHub issue, walk away, and come back to a tested pull request waiting for your approval. That is the workflow we are building in this lesson: Codex as a coding teammate that lives inside your repository and your editor, not a chat window you copy-paste into.
Codex is OpenAI's software engineering agent. It runs in three places that matter here:
- the cloud, in a sandboxed environment connected to your GitHub repos
- your IDE, via the official extension
- the CLI in your terminal
All three use the same underlying agent. They differ in how much autonomy you grant. Start with the official overview in the Codex docs.
The two surfaces: cloud and local
There is one distinction worth fixing in your head before anything else.
Cloud Codex runs each task in an isolated container. It clones your repo, gets its own filesystem, and by default has no internet access while the agent works. This is where the "assign an issue, get a PR" flow lives.
Local Codex (the IDE extension and the CLI) runs on your machine, against your actual working tree. It sees your uncommitted changes and your local tooling. This is where you pair on something live, with you watching every diff.
Same agent, different blast radius. Cloud is for delegating self-contained work. Local is for collaborating in the moment.
Connecting codex to GitHub
In ChatGPT, open Codex and connect your GitHub account. Then grant access to specific repositories (not your whole org). Codex installs a GitHub App with scoped permissions. Once it is connected, you can point a task at any branch and Codex can open pull requests back to that repo.
Each repo also gets a Codex environment. In the environment settings you define the setup script (for example pip install -e ".[dev]"), environment variables, secrets, and whether internet access is allowed. Codex runs the setup script before each task, so tests can run inside the container.
In your editor, install the Codex extension for VS Code (it also works in forks like Cursor and Windsurf). Sign in with your ChatGPT account. A task you start from the IDE can be sent to the cloud and checked later in the Codex dashboard.
Walkthrough: pick up an issue, open a PR
Here is the concrete flow. Say your repo has this issue:
#214: Login form accepts whitespace-only passwords Users can submit a password that is just spaces. Add validation and a test.
1. Assign the task
In the Codex cloud view, select the repo and branch, then describe the task. The most effective thing you can do is paste the issue and reference real files:
Fix issue #214. Insrc/auth/validators.py, reject passwords that are empty or whitespace-only. Match the existingValidationErrorpattern used byvalidate_email. Add a unit test intests/test_validators.py.
Codex starts a container, runs your setup script, reads the relevant files, and plans. Because the environment is sandboxed, it can run your test suite as it works.
2. Let it work, then read the diff
Codex edits the files, runs the tests, and iterates if something fails. When it finishes, you get a summary: what it changed, the commands it ran, and the test output. Read the diff. Treat it exactly like a junior engineer's PR. The agent is fast and tireless, and it still makes mistakes.
3. Open the pull request
If the diff looks right, open a PR directly from Codex. It writes a title and description, references issue #214, and pushes a branch. Your branch protections, required reviewers, and CI all still apply. Nothing merges without your existing rules being satisfied.
That is the loop: issue in, reviewed PR out, with you as the gate.
Codex: assign a GitHub issue and review the PR
Working from GitHub itself
You can also start from GitHub. Once Codex is connected, comment @codex review on a pull request and Codex posts a code review, flagging bugs and risky changes the way a reviewer would. Mention @codex with an instruction (for example @codex fix the failing test in tests/test_validators.py) and it starts a cloud task in that repo's environment. You can also turn on automatic reviews for a repo in the Codex settings, so every new PR gets a first pass before a human looks at it.
Teaching Codex your project with AGENTS.md
Codex does not magically know your conventions. You teach it once, in a file it reads automatically: `AGENTS.md` at the repo root. It is plain Markdown, a README written for the agent instead of for humans. There is no special schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition →. Headings and short bullet points work best.
A good AGENTS.md tells Codex how to run checks, which conventions to follow, and what it must not touch. Keep it short and factual.
# AGENTS.md
## Testing and checks
- Run tests with `pytest -q`.
- Lint with `ruff check .` and type-check with `mypy src/`.
- All three must pass before you propose a PR.
## Conventions
- Follow PEP 8; format with ruff.
- New functions need type hints and a docstring.
- Tests go in tests/ and mirror the src/ path.
## Off-limits
- Never edit files under migrations/ by hand.With this in place, Codex runs your real checks and stays out of directories you have marked off. If pytest fails, it sees the failure and tries again before handing you the PR. You get fewer PRs that break CI the moment they land.
Two details trip people up. Installing dependencies for cloud tasks belongs in the environment's setup script, not in AGENTS.md. And in a monorepo you can put nested AGENTS.md files in subdirectories: the one closest to the file being edited takes precedence. The same file is read by the IDE extension and the CLI, so local and cloud runs follow the same rules.
Codex in the IDE: pairing live
The cloud flow is delegation. The IDE flow is collaboration, and you reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → for it when you want to watch the work happen.
In VS Code with the Codex extension, open the Codex sidebar and describe a change against your open project. A typical local task:
RefactorOrderService.processto extract the discount logic into aDiscountCalculatorclass. Keep behavior identical and update the existing tests.
The difference from the cloud is approvals. Local Codex runs in modes that control how much it can do without asking:
- Read only: it reads and proposes, and you decide what to apply.
- Agent (the default): it edits files and runs commands in the workspace, and asks before going outside it or using the network.
- Full access: it edits, runs commands, and reaches the network without asking.
For daily work, the default Agent mode is the sweet spot. Codex makes edits and runs your tests, and stops to ask before anything beyond the workspace. You stay in the loop without approving every keystroke.
The IDE is also good for understanding code. Highlight a gnarly function, ask Codex to explain it or write tests for it, and it works against the live file with full project context. If a task grows bigger than expected, hand it off to the cloud from the extension and keep working locally.
Knowledge check
1. What is the fundamental distinction between Cloud Codex and Local Codex described in the lesson?
2. According to the lesson, when is it most appropriate to prefer Cloud Codex over Local Codex?
3. The lesson emphasizes that the single most effective thing you can do when assigning a task is to paste the issue and reference real files. Why does this matter?
4. Select ALL statements that correctly describe how Codex connects to GitHub and the IDE.
Select all the correct answers.
5. Select ALL characteristics that are true of Local Codex (the IDE extension and CLI).
Select all the correct answers.
Safety guardrailsSafety guardrailsRules and controls that keep an AI system inside safe, legal and on-brand boundaries, blocking outputs and actions that cross the line.View full definition → you should actually use
Codex ships with conservative defaults so you can loosen them deliberately. These are the real levers.
Sandboxing and network
Cloud tasks run without internet access during the agent phase unless you enable it for that environment. A task cannot quietly exfiltrate code or pull in untrusted packages. If your build needs to fetch something mid-task, enable access and restrict it to an allowlist of domains (package registries, for example). Broad internet access should be a decision you make on purpose.
Approvals are your kill switch
In local modes, the approval prompt is the most important safety feature you have. Commands that reach outside the workspace or the network surface for confirmation. Resist setting everything to full access on a repo that matters. Reserve full autonomy for throwaway branches and experiments.
Branch protection does the heavy lifting
Codex respects your GitHub setup. Every change arrives as a PR on a branch, so your required reviews, status checks, and CODEOWNERS rules still gate the merge. The agent can open a PR. It cannot bypass a protected main. That is why the PR pattern is safer than letting any tool push directly: your human review process is unchanged. An @codex review comment adds a reviewer. It does not replace your human ones.
Secrets stay out of the prompt
Do not paste APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → keys or credentials into task descriptions or into AGENTS.md. For cloud environments that need secrets, use the environment's secrets settings. Secrets are available to the setup script and removed before the agent starts working, which is one more reason to keep them there.
Scope the GitHub app
You granted access to specific repos when you connected GitHub. Keep it that way. Review the granted repos in your GitHub settings every few months and remove the ones Codex never touches.
The mental model: cloud, sandbox, and PR review for delegated work you will not watch; local plus approvals for work you will. In both cases the merge gate is your existing GitHub rules. Never weaken those to make the agent faster.
When to use which surface
A quick decision guide:
- A well-defined, self-contained issue: cloud Codex. Assign it, do something else, review the PR.
- An exploratory refactor you want to steer: the IDE extension in Agent mode.
- A scriptable, repeatable task in CI or a terminal workflow: the Codex CLI (
codex execruns it non-interactively). - A second opinion on a teammate's PR: comment
@codex reviewon GitHub. - A batch of small chores (bump versions, fix lint across files): cloud, one task each, then review the stack of PRs.
The skill is matching the surface to how much you trust the task to run unattended. Environment options and limits change often, so keep the Codex docs and the help center handy.
Key Takeaways
- Drive the loop, not the keyboard. Assign a GitHub issue with specific file references, let cloud Codex produce a PR, and review it like a teammate's work.
- Write an
AGENTS.mdin plain Markdown: how to test and lint, which conventions to follow, which directories are off-limits. Put dependency installation in the environment setup script. - Use GitHub directly when it is faster:
@codex reviewon a PR for a code review, or@codexplus an instruction to start a task. - Pick the surface by autonomy. Cloud for delegated, self-contained tasks; the IDE extension for live pairing where you watch and approve.
- Keep cloud tasks offline unless they need access, keep secrets in the secrets settings, and reserve full access for throwaway branches. Your branch protection rules stay the final gate on
main.
Frequently asked questions
What is Codex and where does it run?
Codex is OpenAI's software engineering agent. It runs in three places: the cloud, in a sandboxed container connected to your GitHub repositories; your IDE, through the official VS Code extension (which also works in forks like Cursor and Windsurf); and your terminal through the CLI. All three use the same underlying agent and differ mainly in how much autonomy you grant it.
What is the difference between cloud Codex and the Codex IDE extension?
Cloud Codex runs each task in an isolated container that clones your repo, with no internet access by default during the agent phase. The IDE extension runs on your machine against your actual working tree, so it sees uncommitted changes and your local tooling. Use the cloud to delegate self-contained work you will not watch, and the IDE to pair live on something you want to steer diff by diff.
How do I get Codex to open a pull request from a GitHub issue?
Connect your GitHub account in Codex, grant access to the specific repository, then create a cloud task that selects the repo and branch and describes the work. The most effective prompt pastes the issue text and names real files, for example the validator file to change and the test file to extend. Codex runs your setup script, edits, runs the test suite, and when the diff looks right you open the PR from Codex itself.
What should go in an AGENTS.md file?
AGENTS.md sits at the repo root and is plain Markdown with no special schema: how to run tests and linters, the conventions to follow, and the directories that are off-limits. Keep it short, with headings and bullet points. Dependency installation belongs in the Codex environment setup script, not in AGENTS.md. In a monorepo you can nest AGENTS.md files in subdirectories, and the one closest to the edited file wins.
Can Codex merge code into main without review?
No. Codex delivers changes as a pull request on a branch, so your required reviews, status checks and CODEOWNERS rules still gate the merge. The agent can open a PR, it cannot bypass a protected main branch. A `@codex review` comment adds one more reviewer on a PR, it does not replace your human reviewers.
Which approval mode should I use for Codex in VS Code?
Agent mode, the default, is the right setting for daily work: Codex edits files and runs commands inside the workspace, and asks before going outside it or touching the network. Read only is useful when you want proposals you apply yourself. Reserve full access, where it edits and reaches the network without asking, for throwaway branches and experiments.
What to do, from this lesson
These actions are compiled in the role's Playbook.
- Write an AGENTS.md with install, test, lint, and off-limits directories
- Set branch protection requiring PR, review, and passing checks before Codex runs