Course / Reference

Codex surface map

Choose a surface by where the work should run and how you want to supervise it. The same Codex configuration can support several surfaces; you do not need a separate setup for each one.

Choose by task

If you need…	Start with	Why
Fast terminal collaboration in the current repo	CLI	Interactive local edits, commands, approvals, and session resumption.
Work beside the code currently open in your editor	IDE extension	Editor context and local execution without changing applications.
Several isolated tasks visible at once	Codex app	Parallel threads, visual diffs, Git controls, and built-in worktrees.
A long task that should run away from your machine	Web / cloud	Hosted execution against a connected GitHub repository.
A repeatable agent step in a script or CI job	`codex exec`	Non-interactive output, exit status, and structured event options.
A second opinion on a local change	`/review`	A dedicated reviewer inspects a diff without changing the worktree.
Visual testing of a local web interface	In-app browser	Codex can navigate, inspect, click, type, and capture the rendered result.
Work that depends on your signed-in browser state	Chrome integration	Uses the user's Chrome profile when existing sessions or extensions matter.
Interaction with a native desktop application	Computer Use	Controls macOS or Windows UI when no direct tool or API fits.

The core surfaces

Local · interactive

CLI

Reads, edits, and runs code in the selected directory.
Supports approval modes, image input, web search, MCP, and slash commands.
Resumes previous threads with codex resume.
Submits hosted tasks with codex cloud.

Local · editor-attached

IDE extension

Works alongside VS Code-family editors and JetBrains IDEs.
Uses open files and selections as immediate task context.
Can perform local work or delegate to Codex cloud.

Local · parallel

Codex app

Runs multiple threads and projects in one desktop workspace.
Creates isolated Git worktrees for parallel changes.
Provides visual diff review and Git operations.
Supports scheduled automations and local UI tools.

Hosted · asynchronous

Web / cloud

Runs in a configured cloud environment against GitHub repositories.
Continues while your local machine is unavailable.
Can produce changes for review or a pull request.
Supports multiple attempts when alternative solutions are valuable.

Local · non-interactive

`codex exec`

Runs one prompt from a script, shell pipeline, or CI system.
Returns a final result to standard output.
Can resume an earlier non-interactive run.
Best reserved for bounded workflows with explicit checks.

Execution and isolation

Surface	Runs where	Repository state	Supervision
CLI	Your machine	Current checkout	Live terminal transcript
IDE	Your machine	Current checkout	Live editor panel
App	Your machine	Checkout or isolated worktree	Parallel thread UI
Web / cloud	OpenAI-hosted environment	Connected repository snapshot	Asynchronous task UI
`codex exec`	Your machine or CI runner	Process working directory	Logs and exit status

Configuration shared across surfaces

One-off task requirement       → prompt / thread
Repository conventions        → AGENTS.md
Repository Codex settings     → .codex/config.toml
Personal Codex defaults       → ~/.codex/config.toml
Reusable workflow             → skill
Installable capability bundle → plugin
External service or live data → MCP server / connector
Mechanical lifecycle control  → hook
Scheduled recurring work      → automation

Coming from Kiro or Claude

Do not duplicate every existing customization immediately. Importing can translate supported instructions, settings, skills, MCP servers, hooks, slash commands, sessions, and subagents while leaving the original setup unchanged. Review permissions and authentication after import, then keep only the pieces that improve the Codex workflow.

High-value complementary roles

Independent reviewer

Let Kiro or Claude implement, then use Codex /review against the local diff.

Parallel investigator

Give Codex an isolated worktree to diagnose or prototype without disturbing the primary implementation thread.

UI verifier

Use browser or computer-control capabilities to verify rendered behavior instead of trusting source inspection alone.

Workflow runner

Move a stable, bounded task into codex exec, a skill, or an automation only after the interactive version is reliable.

Official sources

CLI · CLI features · IDE · App · Web/cloud · Import · Best practices