What Is OpenAI Codex

Codex is OpenAI's coding agent. It reads a repository, plans a change, edits files, runs commands in a sandbox, and hands you a diff to review — from four surfaces that share the same configuration: the Codex app, an IDE extension, a CLI, and a cloud/web environment for longer-running or background tasks. Because all four read the same ~/.codex configuration, an MCP server or plugin you set up once follows you between the terminal and the IDE.

In short: Codex is less a single tool than a runtime — a place where skills, app connections, and MCP servers snap together around a coding task, instead of you rebuilding the same setup in every project.

Why Developers Are Adopting Codex

Most "AI coding assistant" comparisons focus on model quality, but the more interesting shift is structural. Codex separates three things that used to live in one giant system prompt: instructions (AGENTS.md), reusable procedures (skills), and tool access (apps and MCP servers). That separation is what makes plugins possible — a plugin is just a bundle of those three things you can install and uninstall as a unit, instead of pasting boilerplate into every new chat.

The practical result: a team can standardize how Codex reviews pull requests, reads Sentry issues, or drafts documentation, and ship that standard as an installable package rather than a wiki page nobody reads.

Installing and Configuring Codex

The CLI is the fastest place to see configuration take effect. Codex stores settings in ~/.codex/config.toml by default (override with CODEX_HOME for a project-specific profile).

# Open the plugin browser inside the CLI codex /plugins  # Add an MCP server directly from the CLI codex mcp add context7 -- npx -y @upstash/context7-mcp  # See active MCP servers in a running session /mcp

For fine-grained control — timeouts, tool allow-lists, per-tool approval modes — edit config.toml directly. Here's a minimal, realistic block for a streamable-HTTP MCP server:

[mcp_servers.figma] url = "https://mcp.figma.com/mcp" bearer_token_env_var = "FIGMA_OAUTH_TOKEN"  [mcp_servers.figma] startup_timeout_sec = 20 tool_timeout_sec = 45

Plugins vs Skills vs Apps vs MCP

These four terms get used interchangeably in marketing copy, which is exactly why beginners get stuck. Here's the distinction that actually matters when you're deciding what to install.

So when someone says "install the GitHub plugin," what actually lands on your machine can be a skill, an app connection, an MCP server, or all three — the plugin is just the wrapper that makes it installable and shareable.

The Plugin Directory

Codex organizes plugins into three groups, whether you're browsing them in the app or in the CLI:

• Curated by OpenAI — reviewed plugins available to all Codex users.
• Shared with you — plugins another member of your ChatGPT workspace has published internally.
• Created by you — plugins you've scaffolded and added to your own workspace.

Installing is the same everywhere: open a plugin's detail page, select install (or Install plugin in the CLI), connect any external app it needs when prompted, then start a new thread before using it. Your existing approval settings still govern what the plugin is allowed to do once it's live — installing it doesn't grant blanket permissions.

To disable a plugin without removing it, flip its entry in config.toml:

[plugins."gmail@openai-curated"] enabled = false

The Codex Plugin Ecosystem

As of this writing, OpenAI's curated directory centers on a focused set of tools rather than a sprawling app-store catalog — a deliberate choice, since each curated plugin has gone through review. Third-party and workspace-authored plugins extend far beyond this list, but they carry different trust guarantees, so it's worth knowing which is which.

How to read a plugin card

Every plugin in this guide is labeled with what kind of trust boundary it sits behind:

Development

Documentation & Design

Productivity

Debugging

Deployment

GitHub Integration

GitHub gets special treatment because Codex ships both a curated plugin and a deeper first-party integration for it — plus a dedicated GitHub Action for CI-triggered runs. In practice that means three separate entry points: assign Codex to an issue from GitHub's UI, invoke it from the CLI against a checked-out repo, or trigger it from a workflow file on every PR. Teams standardizing on Codex for code review usually start with the Action, since it doesn't require every contributor to have Codex configured locally.

Figma Integration

Figma connects to Codex through Figma's own MCP server rather than a Codex-side integration, in both a local (desktop app) and remote (hosted) flavor. This is a good illustration of the plugin model at its best: OpenAI didn't have to build Figma-specific tooling, it just had to support MCP well, and Figma's own server does the rest. The trade-off is that server behavior, rate limits, and reliability live outside OpenAI's control.

Notion Integration

The curated Notion plugin bundles page and database read/write with skills tuned for turning engineering output — commit logs, PR summaries, incident timelines — into structured Notion content. It's one of the clearer wins for teams that already treat Notion as the source of truth for decisions, since it removes the "someone has to manually update the doc" step.

Slack Integration

Like GitHub, Slack has both a curated plugin and a deeper native integration. The practical difference shows up in latency-sensitive workflows: native integrations tend to support richer triggers (a Codex run kicked off from a Slack message, not just Codex posting to Slack), where a plugin alone is typically one-directional from Codex into the channel.

Sentry Integration

Sentry is arguably the highest-leverage plugin for a team already shipping fast, because it collapses "notice the error → find the stack trace → find the commit → propose the fix" into a single conversational loop. The catch: Codex will happily propose a fix for a stale or duplicate issue if you don't scope the query (open issues, last 24h, specific project), so specificity in the prompt matters more here than almost anywhere else in this guide.

Browser Automation

For anything that lives in a browser rather than an API — visually verifying a UI change, scraping a page that has no public API, driving a login flow — Codex reaches for browser MCP servers rather than a dedicated "browser plugin." The two the docs call out most are Playwright and Chrome DevTools, both controllable through MCP. The Codex app also ships its own in-app browser and a Chrome extension for tighter loop between "look at the page" and "edit the code."

Terminal Workflow

The CLI is where plugin and MCP configuration actually gets exercised day to day. A few commands worth memorizing:

/plugins        # browse, install, toggle plugins by marketplace /mcp            # list active MCP servers in this session codex mcp add   # add a new MCP server from the shell codex mcp --help

In the plugin browser's marketplace tabs, pressing Space on an installed plugin toggles it on or off for the current session — useful when you want to rule out a plugin as the cause of an unexpected tool call without fully uninstalling it.

AGENTS.md

AGENTS.md is the single most underused lever in most Codex setups. Codex reads it before doing any work, building an instruction chain from a global file in ~/.codex/AGENTS.md down through every directory between your project root and your current working directory — each nested file layering on top of, or overriding, the ones above it.

# AGENTS.md  ## Repository expectations - Run `npm run lint` before opening a pull request. - Document public utilities in docs/ when you change behavior.

Nested AGENTS.override.md files let a specific subdirectory (say, a payments service with stricter rules) fully replace the guidance above it rather than append to it — useful in monorepos where "run the tests" means something different in every package.

Memory

Codex's local memory system is separate from ChatGPT's web memory and is off by default. Once enabled, Codex can turn context from idle, eligible past sessions into local memory files under ~/.codex/memories/, redacting secrets as it goes and skipping short-lived chats so it isn't summarizing work that's still in progress.

[features] memories = true

Two settings worth knowing: memories.use_memories controls whether past memories get injected into new sessions, and memories.disable_on_external_context keeps chats that relied on web search or MCP tool calls out of memory generation entirely — handy if you don't want a Sentry-triage session polluting memory with someone else's stack trace.

Prompt, Context, and Loop Engineering

Three related but distinct skills separate developers who fight Codex from developers who fly through a backlog with it.

Prompt engineering

Say what you want changed and what "done" looks like, not just the symptom. "Fix the flaky checkout test" is weaker than "the checkout test fails intermittently on the discount-code assertion — reproduce it, find the race condition, and add a regression test."

Context engineering

This is about what Codex has access to, not what you type: the right AGENTS.md scope, the right MCP servers enabled, the right files open. A perfectly worded prompt still fails if Codex can't see the config file that actually controls the behavior you're asking about.

Loop engineering

The practice of designing repeatable propose → run → check → repeat cycles instead of one-shot prompts — for example, wiring Codex to run the test suite after every change and keep iterating until it's green, rather than reviewing each attempt by hand. Codex's cookbook documents this pattern directly for iterative repair loops.

Multi-Agent and Subagent Workflows

Codex supports subagents — scoped agent instances a primary Codex session can delegate specific pieces of work to. The practical use case is parallelizing independent work: one subagent runs the test suite and reports back while the primary session keeps editing, rather than one agent doing everything serially. This is a newer and more advanced surface than plugins or MCP, and it's worth treating it as an optimization once your single-agent workflow is already reliable, not a starting point.

Real Workflows, Step by Step

1. Build a React application with Codex

Scaffold with a clear AGENTS.md in place first (package manager, test command), then prompt for the feature in outcome terms. Ask for tests alongside the component, not as an afterthought.

2. Fix production bugs using the Sentry plugin

Scope the query, ask for root cause before a fix, and require a regression test in the same diff.

3. Generate UI directly from Figma

Point Codex at a specific frame, not a whole file — large files slow down MCP inspection and increase the chance of pulling in unrelated components.

4. Write documentation from GitHub commits

5. Refactor a legacy codebase

Ask for a plan before code. Legacy refactors are where loop engineering earns its keep — have Codex refactor one module, run the suite, and only continue once it's green.

6. Review pull requests automatically

The GitHub Action is the right entry point here — trigger Codex review on every PR rather than relying on someone remembering to ask for it manually.

7. Generate SQL migrations

Without a curated database plugin, this typically runs through a project-scoped MCP server for your database, with the migration always reviewed and applied manually rather than auto-executed.

8. Deploy to Vercel

Keep production deploys behind a manual approval step even once preview deploys feel routine.

Best Practices

Dos

• Keep AGENTS.md scoped and specific — one clear rule beats five vague ones.
• Start new plugins in prompt approval mode before switching to auto.
• Uninstall plugins you're not actively using — every installed tool is attack surface.
• Scope MCP server credentials to the minimum the task needs.

Don'ts

• Don't rely on memory for rules that must always apply — use AGENTS.md.
• Don't grant a plugin production write access "to save a step" — the step it saves is the one that catches mistakes.
• Don't stack unrelated MCP servers into one session just because they're installed — each one adds tokens to context and a chance of tool confusion.

Mistakes beginners make

• Treating a plugin's install as a one-time decision instead of revisiting its permissions as the project matures.
• Writing prompts that describe the symptom instead of the desired end state.
• Skipping AGENTS.md entirely and re-explaining project conventions in every single prompt.

Repository organization checklist

• A root-level AGENTS.md with test command, package manager, and forbidden actions
• Nested AGENTS.override.md only where a subdirectory genuinely differs
• Project-scoped .codex/config.toml for MCP servers specific to this repo
• A short list of which plugins are approved for this repo and why

FAQ

Conclusion

The plugin system is what turns Codex from a very good autocomplete into an agent that can actually sit inside your team's real tools — GitHub, Figma, Sentry, Slack, Notion — without you building glue code for any of it. None of that replaces good judgment: review the diffs, scope the approval modes, and keep AGENTS.md honest. Start with one plugin that removes a real daily annoyance, get comfortable with its approval settings, and expand from there. The workflow that saves you the most time is rarely the most elaborate one — it's the one you actually keep using.