Codex in the Cloud and Integrations
Delegate a task to Codex cloud, walk away, and come back to a pull request — this lesson teaches you to use Codex as an async contributor, not just a session-bound tool.
The Shift From Tool to Contributor
Most developers first experience Codex as a session tool: you open the CLI, describe what you want, watch it work, and steer it in real time. That is a powerful workflow. But it puts a ceiling on what you can delegate — you are still present for the whole process.
Codex cloud removes that ceiling.
The cloud model is fundamentally different: you describe a task, submit it, and walk away. A sandboxed environment clones your repo, starts an agent loop, reads your AGENTS.md for context, implements the change, runs the checks, and opens a pull request. When you come back, the PR is waiting for your review. You were not blocked. You were doing other work.
This is not a chatbot with extra steps. It is an async contributor with a fixed interface: you give it a task, it gives you a PR, you review the diff. The agent relationship is the same one you have with a junior engineer who works asynchronously and hands off via GitHub.
AGENTS.md — The Contract Codex Reads
Every Codex cloud task starts by reading AGENTS.md in the root of your repository. This file is the contract that tells Codex how to work in your codebase.
A well-written AGENTS.md covers:
Conventions the agent must follow. Naming patterns, file structure, import style, test file location — anything Codex needs to write code that looks like it belongs in your codebase rather than code that technically works but violates every convention your team has.
Directories that are off-limits. Production configs, auto-generated files, files that must only be edited by a specific pipeline. Naming these explicitly prevents Codex from touching things it should not touch.
Checks that must pass before opening a PR. The test command, the lint command, the type check command. If Codex opens a PR with a failing test, it did not follow the contract. AGENTS.md is where you enforce that requirement.
Project-specific context. Architecture decisions, known issues, libraries in use, relevant background. The more context you provide, the less Codex has to infer.
Writing AGENTS.md is one of the highest-leverage activities in a Codex workflow. A good AGENTS.md converts Codex from "does the right thing most of the time" to "follows your spec consistently."
Integrations: Where Tasks Come From
Codex cloud does not require you to navigate to a web UI every time you want to delegate a task. It integrates directly with the tools where work already lives.
GitHub is the native home for code tasks, and the integration is mention-driven. In a pull-request comment you write @codex review to get an automated code review, or @codex followed by any other instruction — @codex fix the failing test, @codex add input validation — to kick off a cloud task that pushes commits back to the PR. You can keep the conversation going in review comments — "this approach won't handle concurrent requests" — and Codex responds to the feedback and pushes updated commits. The entire workflow stays inside GitHub, driven by @codex mentions on pull requests rather than by issue assignment.
Slack is where team decisions happen and where ad hoc tasks arise. The Slack integration lets you mention @codex in a channel or DM, describe a task in natural language, and receive a notification when the PR is ready. The task brief lives in the Slack thread; the artifact lives in GitHub. You do not need to leave your current context to delegate.
Linear is the integration for teams that track work in a project management tool. Assign a Linear ticket to Codex, and when the PR opens, the ticket status updates automatically. When the PR merges, the ticket closes. For teams that use Linear as their single source of truth for work state, this integration eliminates the manual "update the ticket" step that everyone forgets.
Cloud vs. Local CLI: The Decision
The right tool depends on what you need from the interaction.
Use Codex cloud when:
- The task is well-defined and you can write clear acceptance criteria upfront
- The task will take longer than a few minutes of compute time
- You want to parallelize — run multiple Codex tasks simultaneously while you work on something unrelated
- The output is a PR, not an interactive session
Use Codex CLI locally when:
- You need to steer the agent mid-task based on what you observe
- The problem is exploratory — you are not sure exactly what the solution looks like and you want to discover it interactively
- You need immediate feedback, not async delivery
- You are debugging something where the investigation itself is the work
Writing a Good Task Brief
The quality of a Codex cloud task output is roughly proportional to the quality of the task description. A vague brief produces a vague PR. A precise brief produces a precise PR.
A good task brief for Codex cloud has four components:
A specific title. Not "fix the bug" but "fix the null pointer exception in UserService.getActiveSubscription when user has no payment method on file."
Context Codex needs. Which part of the codebase is involved, what the expected behavior is, any relevant background (previous attempts, known constraints, dependencies).
Acceptance criteria. What does done look like? Which tests should pass? What should a user experience when the fix is working? Specific, checkable outcomes — not "it should work."
Files in scope. Optional, but useful for large codebases. Naming the files that should and should not be touched prevents Codex from making changes in unexpected places.
The BuildChallenge for this lesson asks you to write a function that takes a rough task description and structures it into a proper brief. This is a workflow tool you will use every time you delegate to Codex cloud.