An OpenAI Codex workshop should follow one piece of work all the way through: briefing the agent with AGENTS.md and a clear task, running it locally in the CLI or as a cloud task, reviewing the diff, iterating and merging a pull request. Teams learn when to use local, interactive runs versus parallel cloud tasks, and how to keep approval and sandbox settings safe.
On this page
OpenAI Codex is a family of agentic coding surfaces: at the time of writing it includes an open-source command-line agent that runs on your machine, an IDE extension and cloud tasks that run in isolated environments and can propose pull requests. That flexibility is useful, but it also confuses teams about which mode to use for what. A good Codex workshop is built around a single question: how does a task travel from first prompt to merged pull request without losing quality on the way? This article describes that journey stage by stage.
Stage 1: Prepare the repository for an agent
Codex reads AGENTS.md files for project instructions. Before anyone writes a prompt, the team should create one that explains how to install dependencies, run tests and linters, where key modules live and which conventions matter. The workshop treats AGENTS.md as code: it is reviewed, versioned and improved whenever the agent makes an avoidable mistake. Cloud tasks also need an environment definition, including setup scripts and dependency installation, so participants practise making a repository bootable in a fresh container. A repository that a new human developer cannot set up in minutes will also slow down an agent.
Stage 2: Write a task the agent can finish
Codex performs best with tasks that have a clear finish line. In the workshop, participants rewrite vague backlog tickets into agent briefs with a goal, constraints, relevant files and acceptance criteria, ideally a test command that must pass. We contrast weak and strong briefs on the same ticket and compare the resulting diffs. The general principles are covered in our article on prompting code agents with briefs and specs; the Codex workshop applies them to the team's actual backlog.
Stage 3: Choose local or cloud execution
Local runs in the CLI or IDE are interactive. The developer watches the agent, answers questions and steers. Cloud tasks run in the background, several at once, and return a diff or pull request for review. Both have a place, and the workshop gives teams a simple decision rule.
| Situation | Better fit | Why |
|---|---|---|
| Exploring unfamiliar code or a fuzzy problem | Local CLI or IDE | Fast feedback, easy to redirect |
| Well-specified, independent tickets | Cloud tasks | Can run in parallel while developers do other work |
| Changes needing local services or hardware | Local CLI | Cloud environments may not reproduce them |
| Generating several alternative approaches | Cloud tasks | Compare versions side by side before choosing |
Background agents change how a team plans its day, which we discuss further in background and cloud coding agents.
Stage 4: Approvals and sandboxing
The Codex CLI offers approval and sandbox settings that control whether the agent can edit files, run commands or access the network without asking. Teams should agree on defaults: a conservative mode for day-to-day work on developer machines and more autonomy only inside disposable environments. Participants practise what happens when the agent requests a command it should not run, and how to deny it gracefully. Because option names and defaults evolve, the workshop always checks the current behaviour against the official documentation on platform.openai.com rather than relying on slides.
Stage 5: Review, iterate, merge
This is where most teams lose time. Agent-generated pull requests can look clean while hiding subtle issues: tests that assert the wrong thing, error handling removed to make a test pass or dependencies added without discussion. The workshop runs a structured review drill. Participants receive Codex-generated pull requests, some seeded with problems, and practise reviewing them against a checklist. They also learn to send focused follow-up instructions instead of starting over, and when it is faster to fix a detail by hand. Our separate AI-assisted code review workshop expands this into a full exercise set.
Teams using GitHub can also try automated code review features that Codex offers at the time of writing, and decide whether those comments help or add noise.
Putting the stages into a one-day workshop
A one-day Codex workshop typically follows the stages above: a morning on setup, AGENTS.md and task writing with local runs, and an afternoon on cloud tasks, review drills and team conventions. Each participant should leave having merged at least one real, reviewed pull request created mostly by Codex. That single experience, done end to end with proper review, is more convincing than any demo.
Typical mistakes and how to avoid them
Launching ten cloud tasks at once without a review plan creates a queue nobody wants to work through. Start with two or three parallel tasks per person. Another mistake is letting the agent install new libraries freely; require approval for dependency changes. Finally, do not skip the environment setup step. Many failed cloud tasks are not reasoning failures at all but missing dependencies or environment variables.
Getting started
We use Codex alongside other agents to build and launch digital products, so our training reflects production constraints rather than vendor demos. The OpenAI Codex workshops at neooutput are available remote or on-site, in English or German, and can be combined with Claude Code or Cursor if your team uses several tools.
Frequently asked questions
What is the difference between the Codex CLI and Codex cloud tasks?
The CLI runs the agent locally on your machine with interactive control, while cloud tasks run in isolated remote environments in the background and return diffs or pull requests. Many teams use both for different kinds of work.
Does Codex use AGENTS.md or another file?
Codex reads AGENTS.md files for repository instructions. Other agents increasingly support the same file, which makes it a good shared format for teams using several tools.
Can a Codex workshop run on our private GitHub repositories?
Yes, as long as your organisation allows connecting Codex to those repositories. Clarify access rights and data policies with your security team before the workshop.