CODEX
COING
101
This is a polished operating guide for using Codex in the desktop app and in VS Code, written for beginners through senior AI developers. It covers practical setup, prompt blueprints, hidden productivity wins, advanced command usage, automations, how Codex behaves as a tool-calling coding agent, and a set of high-signal external repos and cookbooks for real-world examples.
Codex is not just a chat interface. In practice it behaves like a coding agent with repo context, a planning loop, tool access, diff generation, validation, and review steps. For senior AI developers, the useful mental model is: Codex = model + execution harness + tools + state + review workflow.
Codex App
Best full workflow shell: threads, worktrees, Git diff pane, commit/PR flow, automations, local terminal, and in-app project switching.
VS Code Extension
Best day-to-day development surface when you want file selections, command palette actions, recent editor context, and quick cloud handoff.
CLI
Best keyboard-first interface with deep command control, profiles, MCP management, resume/fork flows, and automation-friendly execution modes.
Cloud + GitHub + Automations
Best for parallel tasks, PR reviews, recurring jobs, and workflows that should continue beyond one local session.
Use the app when you want the strongest workflow shell. Use VS Code when you want the tightest coding loop. Use the CLI when you want total command-line control. Use Cloud and GitHub when you want Codex working in parallel with you rather than under your cursor.
Install, launch, and upgrade Codex CLI
These commands match the current official CLI docs.
Add the official OpenAI developer docs as an MCP server
Useful for current model, API, and Codex guidance inside your editor or CLI.
Install the extension from the marketplace and sign in
The current IDE docs say the extension works with Visual Studio Code and VS Code forks like Cursor and Windsurf. In VS Code it opens in the right sidebar by default after install, and it prompts you to sign in with ChatGPT or an API key.
The IDE docs currently say Windows support is experimental. For the best Windows experience in the extension and CLI, use a WSL2 workspace.
Install the Codex app from the Microsoft Store or with winget
The Windows app can run natively with PowerShell and Windows sandboxing, or through WSL2.
Open one repo, start one thread, ask for a plan first, let Codex inspect before editing, run validation, then review the diff before you accept changes.
Use the app when you want project switching, thread management, worktrees, built-in Git review, local terminal visibility, and automations from one place.
Use it when you want to highlight code, add file context directly, stay in your editor, and still switch between local and cloud execution.
Use the CLI when you want slash commands, exact profiles, MCP control, inline images, automation-friendly exec mode, and session forking or resuming.
Use cloud when you want a task to keep running remotely, or when you want to compare alternate attempts without tying up your local environment.
The current GitHub integration docs support PR review comments like @codex review and other task prompts such as CI triage and cloud task handoff.
App Slash Commands
/feedbacksubmit feedback and optionally attach logs/mcpopen MCP status and connected servers/plan-modetoggle plan mode for complex tasks/reviewreview uncommitted changes or compare to a base branch/statusshow thread id, context usage, and rate limits
VS Code Slash Commands
/auto-contexttoggle auto-inclusion of recent files and IDE context/cloudswitch to cloud mode/cloud-environmentpick the cloud environment/localswitch back to local mode/reviewstart review mode/statusinspect thread and context state
VS Code Command Palette
chatgpt.addToThreadadd selected text range to current threadchatgpt.addFileToThreadadd the current file to thread contextchatgpt.newChatcreate a new threadchatgpt.implementTodoask Codex to address the selected TODOchatgpt.newCodexPanelopen a new Codex panelchatgpt.openSidebaropen the Codex sidebar panel
CLI Power Commands
/modelswitch active model/permissionschange approval behavior mid-session/statusinspect model, policy, roots, and token usage/reviewreview local diff/compactsummarize older context to stay lean/forkbranch a session while preserving transcript/resumecontinue earlier sessions/planswitch directly into planning mode/copycopy the latest response/debug-configinspect config precedence and policy sources/statuslinecustomize footer status fields/titlecustomize terminal title fields/psinspect background terminals/stopstop background terminals
| Command | Where | Why it matters |
|---|---|---|
codex review | CLI | Run a code review non-interactively when you want a review pipeline or a shell-based second pass. |
codex resume --last | CLI | Jump back into the most recent session fast. |
codex fork --last | CLI | Create a new attempt from the latest session without destroying the original line of reasoning. |
codex completion powershell | CLI | Generate PowerShell shell completions for faster local command use. |
codex features list | CLI | Inspect current feature flags and stages. |
codex login status | CLI | Check auth status when a surface behaves unexpectedly. |
The Codex prompting guidance and GPT-5-Codex cookbook both reinforce a useful principle: less is often more. Codex already knows how to code, inspect, plan, and validate. The main prompt job is to specify the task boundary, constraints, validation, and what good looks like.
Debug a bug
Review a diff or PR
Understand a codebase
Build a new application
UI / UX iteration
This is the missing operating layer most teams need. If you want Codex to behave consistently, you need repo guidance, reusable workflows, and a planning convention for larger work. The official best-practices docs emphasize AGENTS.md, the skills docs emphasize SKILL.md, and the cookbook shows how PLANS.md can drive long-running implementation work.
What AGENTS.md Should Contain
repo layoutimportant directories and entry pointsrun commandsdev server, scripts, env expectationsbuild / test / lintexact commands Codex should runreview expectationsPR standards and done criteriaconstraintsdo-not rules and safety boundaries
What a Skill Should Do
trigger narrowlybe explicit about when it should and should not triggerstay reusableencode repeatable workflows, not one-off contextuse progressive disclosurekeep the metadata short; load detail only when neededinclude scripts only when neededuse code if it improves reliability
Use AGENTS.md + PLANS.md for larger multi-step work
The Codex cookbook’s PLANS.md pattern is explicitly designed for multi-hour problem solving. It recommends teaching Codex, through AGENTS.md, when to use a planning document, then keeping the plan as a living design-and-implementation artifact.
The cookbook shows this pattern supporting very long Codex runs. The win is not just planning quality. It is restartability: the plan becomes a self-contained artifact that both humans and agents can resume from.
Start with /init for repo guidance
The best-practices docs explicitly call out /init as the quick-start command to scaffold a starter AGENTS.md in the current directory.
Minimal high-signal AGENTS.md blueprint
Minimal skill blueprint
Prompt Codex to run a disciplined implementation loop
The best-practices docs explicitly call out writing or updating tests, running the right test suites, checking lint/format/type checks, confirming behavior, and reviewing the diff.
Prompt -> AGENTS.md -> Skill -> Plugin -> Automation
Promote stable knowledge upward. Do not keep paying token tax for reusable instructions.
Use cloud for comparison runs
A strong expert pattern is to keep local work moving while one or more remote tasks explore alternate implementations.
Use PLANS.md for multi-hour tasks
The Codex cookbook includes an explicit pattern for long-running work using PLANS.md. Use this for migrations, deep refactors, or broader system changes where you want implementation to follow a reviewed design document.
Review-first engineering
Codex is at its best when the loop includes tests and review, not just generation. For senior teams, this means treating it as part of your software delivery process rather than a one-shot assistant.
Use screenshots and multimodal input intentionally
The official use cases and frontend guidance consistently show that UI work gets better when you attach screenshots, visual references, or design inputs instead of describing layouts in prose.
The current app docs define automations as recurring background Codex tasks. Results go to the app inbox / Triage when there is something to report, or the task can auto-archive when there is nothing notable.
Standalone / Project Automations
Fresh run each timebest when every scheduled run should be independentMultiple projectscan run across one or more projectsTriage outputfindings show up as separate automation runsWorktree optionideal for isolation in Git repositories
Thread Automations
Heartbeat stylewake up the same thread on a scheduleSame contextbest when continuity mattersMinute / daily / weeklysupports active follow-up loops and check-insGood forpolling GitHub, Slack, long-running checks, ongoing triage
Automation execution model
The current app docs say automations run in the background, use your default sandbox settings, can use the same plugins and skills available to Codex, and in Git repos can run either in your local project or in a dedicated background worktree.
Skills define the method; automations define the schedule
The docs explicitly recommend using skills to keep automations maintainable and shareable. You can trigger a skill from an automation with $skill-name.
Manual thread first, schedule second
The docs explicitly recommend testing the prompt manually in a normal thread before scheduling it. This is the right pattern: prove that the task is reliable manually, then automate it.
Automations run unattended
That makes sandbox and approval choices more important. Read-only blocks many useful operations. Full access raises risk. Workspace write plus targeted rules is usually the right middle ground.
Automations are how Codex stops being just an interactive agent and starts behaving like programmable engineering labor. The stable pattern is: human-designed prompt + durable repo guidance + optional skill + scheduled execution + inbox review.
How To Draw / Generate Images
For product work inside Codex, the main pattern is multimodal: attach screenshots or visual references for UI tasks. For actual image output, OpenAI’s image generation docs recommend the image generation tool in the Responses API or the Image API with GPT Image models.
attach screenshotsbest for UI fixes and redesignsimage_generation toolbest for creating or editing raster images in API workflowsgpt-image-1.5OpenAI’s current top image generation model in the docs
How To Build PowerPoint / Slide Decks
The official Codex use cases explicitly include generating slide decks. In the local plugin cache on this machine, the SharePoint plugin exposes a sharepoint-powerpoint skill specifically for creating, editing, restyling, and reviewing PowerPoint .pptx files while preserving deck style.
generate slide decksofficial Codex use casesharepoint-powerpointstyle-preserving PowerPoint workflow from SharePointrendered visual QArecommended when slide fidelity matters
Available plugin-backed options in this Codex install
The local plugin marketplace cache on this machine includes teams, outlook-email, outlook-calendar, and sharepoint. That gives you practical Microsoft workflow coverage for chat summarization, inbox triage, calendar context, SharePoint documents, spreadsheets, and PowerPoint decks.
Teams can also drive Planner task workflows
The local Teams plugin skills include channel summarization, notification triage, reply drafting, and Planner task management. That makes it a good surface for turning meeting or channel follow-ups into trackable work.
Use Atlassian Rovo for Jira and Confluence
The local plugin metadata identifies atlassian-rovo as “Manage Jira and Confluence fast.” Its bundled skills include converting specs to backlogs and triaging issues, which is exactly the kind of high-value PM + engineering bridge workflow many teams need.
Use the GitHub plugin for PRs, issues, CI, and publish flows
The local GitHub plugin metadata describes it as a hybrid GitHub connector and CLI workflow for repositories, pull requests, issues, CI, and publishing changes. Its local skills include addressing review comments and fixing CI.
Use plugins when the workflow lives outside the repo
The official Codex docs already expose Slack and Linear as integrations, and the local plugin marketplace cache here also includes slack, linear, notion, figma, and many others. The correct pattern is to install the plugin, start a new thread, then describe the outcome you want.
Think "tool-calling agent"
For senior AI developers, the right model is close to function calling or tool orchestration rather than plain chat. Codex receives a task, maintains thread state, decides when to inspect code, when to use shell or review tools, when to read docs through MCP, and when to return a diff or review output.
Typical execution path
Prompttask, constraints, validation targetPlanCodex decides a work strategyToolsshell, Git, MCP, web/docs, images, skillsPatch / diffimplement or review outputValidationtests, lint, direct reproReviewfinal inspection before acceptance
AGENTS.md supplies durable repository behavior
The best-practices docs explicitly position AGENTS.md as the default place for repo-specific agent rules such as how to build, test, lint, review, and define done.
Skills supply reusable workflows with progressive disclosure
The skills docs explain that Codex loads skill metadata first and only loads the full SKILL.md when it decides the skill is relevant. That is a context-efficiency pattern, not just a packaging detail.
MCP connects Codex to external tools and live systems
MCP is the tool / connector layer. Use it when the needed context is outside the repo or changes frequently.
Cloud, GitHub, and automations extend the same agent pattern
Cloud offloads runs, GitHub triggers tasks from comments or PRs, and automations schedule the work. These are not separate products conceptually; they are alternate execution surfaces for the same tool-using Codex workflow.
The commands below are operational maintenance commands. Some are official CLI commands. The cleanup examples are manual filesystem operations based on the local Codex home layout on this machine. Use them intentionally and back up first if you care about preserving local history.
Official Maintenance Commands
codex login statuscheck whether auth is validcodex logoutremove stored credentialscodex loginsign in againcodex features listinspect effective feature flagscodex completion powershellgenerate shell completionscodex resume --lastre-open your latest sessioncodex fork --lastcreate an alternate branch of the last session
Manual Local Housekeeping
%USERPROFILE%\.codex\cachecache files%USERPROFILE%\.codex\sessionssession history by year%USERPROFILE%\.codex\archived_sessionsarchived session logs%USERPROFILE%\.codex\logs_2.sqlitelocal logs database%USERPROFILE%\.codex\auth.jsonstored authentication metadata
Inspect local Codex state
Remove cached files only
This is the lowest-risk cleanup step if Codex metadata feels stale.
Review sessions before deleting anything
Delete archived history only
This is safer than deleting active session history under sessions.
Reset authentication cleanly
Current product docs do not expose a first-class “clear all history” command. In practice, the right controls are: start a new thread, use /compact, use /fork for alternate branches, use /resume for continuity, and only do manual cleanup when you intentionally want to remove local stored state.
If this document is meant to help promote Codex internally or externally to senior AI developers, include living examples. The links below are the highest-signal ones I found for prompt examples, durable patterns, and real generated outputs.
OpenAI GPT-5 Coding Examples
A curated repository of apps generated from single prompts. Good for showing what “prompt to runnable artifact” looks like in practice.
https://github.com/openai/gpt-5-coding-examplesCodex Cookbook Topic
Central landing page for Codex cookbooks such as the Codex Prompting Guide, PLANS.md workflow, CI failure autofix, and code review patterns.
https://cookbook.openai.com/topic/codexGPT-5-Codex Prompting Guide
Strong source for the “less is more” guidance that senior prompt engineers will care about.
https://cookbook.openai.com/examples/gpt-5-codex_prompting_guidePLANS.md for Multi-Hour Problem Solving
Useful for teams that want reviewed implementation plans before long-running agent work starts.
https://cookbook.openai.com/articles/codex_exec_plansOpenAI Codex Repository
Useful for engineers who want to inspect the open-source CLI project and see examples of real AGENTS.md usage in the repo itself.
Codex Prompt Refinery
Community project focused on mining Codex histories into reusable prompt clusters. Useful if your team wants to operationalize prompt reuse.
https://github.com/BjornMelin/codex-prompt-refineryMinecraftCodex
Older Microsoft demo, but still useful because it explicitly includes prompt assets in the repo and shows prompt-driven behavior control in code tasks.
https://github.com/microsoft/MinecraftCodexCodex Use Cases
Official use cases page, useful when presenting Codex to stakeholders who want concrete workflow examples such as PR review, UI work, skills, and codebase understanding.
https://developers.openai.com/codex/use-casesOpenAI Image Generation Guide
Use this when your Codex workflow needs actual generated or edited images, not just screenshot-based UI iteration.
https://platform.openai.com/docs/guides/image-generationDo This
One thread per taskkeeps context coherent and token-efficientPlan before broad workprevents premature edits and scope driftMove durable rules to AGENTS.mdstop repeating yourself manuallyUse skills for recurring workflowskeep context lean through progressive disclosureAttach screenshots for UIbetter than long visual proseUse review modefind regressions before you accept codeUse worktreesavoid overlapping file edits across live tasksAutomate only proven workflowsmanual first, scheduled second
Avoid This
One giant thread per repobloats context and quality decays over timeOverpromptingCodex often gets worse when the harness is too verboseFull access by defaultespecially before you trust the repo workflowPrompting instead of toolinguse MCP when the data is external and dynamicRecurring job without a skillharder to maintain, share, and debugSkipping verificationgeneration without tests or review is not an engineering workflow
Codex is most impressive when you stop using it as a conversational novelty and start using it as a disciplined engineering system: scoped threads, durable repo guidance, reusable workflows, explicit validation, review loops, and the right execution surface for the job.