# Codex on GitHub and in the IDE
You can hand Codex a GitHub issue, walk away, and come back to a reviewed, 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 (a sandboxed environment connected to your GitHub repos), your IDE (via the official extension), and the CLI / terminal. They share the same underlying agent but differ in how much autonomy you grant. Start with the official overview at the Codex docs.
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 network access mid-task. 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.
In your editor, install the Codex extension for VS Code (and forks like Cursor) or the JetBrains plugin. Sign in with your ChatGPT account. The extension shares your Codex environment, so a task you start in the IDE can be inspected later in the cloud dashboard.
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.
In the Codex cloud view, select the repo and branch, then describe the task. The single most effective thing you can do is paste the issue and reference real files:
> Fix issue #214. In src/auth/validators.py, reject passwords that are empty or whitespace-only. Match the existing ValidationError pattern used by validate_email. Add a unit test in tests/test_validators.py.
Codex spins up a container, reads the relevant files, and plans. Because the environment is sandboxed, it can run your test suite as it works.
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 this exactly like a junior engineer's PR: the agent is fast and tireless, not infallible.
If the diff looks right, click to open a PR directly from Codex. It writes a title and description, links issue #214, and pushes a branch. Your normal 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 does not magically know your project's conventions. You teach it once, in a file it reads automatically: AGENTS.md at the repo root. Think of it as a README written for the agent instead of for humans.
A good AGENTS.md tells Codex how to install dependencies, how to run tests, and which conventions to honor. Keep it tight and factual.
# AGENTS.md (front-matter style config Codex reads)
setup:
- pip install -e ".[dev]"
checks:
test: pytest -q
lint: ruff check .
typecheck: mypy src/
conventions:
- Follow PEP 8; format with ruff before committing.
- All new functions need type hints and a docstring.
- Tests go in tests/ and mirror the src/ path.
- Never edit files under migrations/ by hand.
before_pr:
- Run test, lint, and typecheck. All must pass.With this in place, Codex installs the right way, runs your real checks, and refuses to touch directories you have marked off. If pytest fails, it sees the failure and tries again before handing you the PR. The result: fewer PRs that break CI the moment they land.
You can also place nested AGENTS.md files in subdirectories for monorepos, and the closest one wins for files in that path.
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:
> Refactor OrderService.process to extract the discount logic into a DiscountCalculator class. 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:
For day-to-day work, the middle mode is the sweet spot. Codex makes edits and runs your tests, but stops to ask before, say, deleting files or running a command it has not been pre-approved to run. You stay in the loop without babysitting every keystroke.
The IDE flow also shines 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.
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.
Codex is designed to be safe by default, but the defaults are conservative precisely so you can loosen them deliberately. Know the real levers.
Cloud Codex tasks run without network access during execution unless you explicitly enable it. This is a deliberate guard: a task cannot quietly exfiltrate code or pull in untrusted packages. If your build genuinely needs to fetch dependencies, enable network access for that environment and prefer pinning what it can 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 →. Treat broad network access as a decision, not a default.
In local modes, the approval prompt is the most important safety feature, not an annoyance. Commands that modify your system or 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 → outside the workspace surface for confirmation. Resist the urge to set everything to full access on a repo that matters. Reserve full autonomy for throwaway branches and experiments.
Codex respects your existing GitHub setup. Because every change arrives as a PR on a branch, your required reviews, status checks, and CODEOWNERS rules still gate the merge. The agent can open a PR; it cannot bypass a protected main. This is why the "open a PR" pattern is safer than letting any tool push directly: your human review process is unchanged.
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. For cloud environments that need secrets to run tests, use the environment's secret configuration rather than inlining them. Anything in the prompt is part of the task context; keep credentials in the secret store where they belong.
When you connected GitHub earlier, you granted access to specific repos. Keep it that way. There is no reason to give the Codex GitHub App access to repositories it will never touch. Review the granted repos periodically in your GitHub settings.
A simple mental model: cloud + sandbox + PR review for delegated work you will not watch, and local + approvals for work you will. In both cases, the merge gate is your existing GitHub rules, and you should never weaken those just to make the agent faster.
A quick decision guide:
The skill is matching the surface to how much you trust the task to run unattended. For the practical setup details and limits, keep the help center Codex articles handy, since exact environment options evolve.
main. Do not weaken them to go faster.These actions are compiled in the role's Playbook.