Introducing a new way to review your PRs.

Read the announcement

openai / codex

Lightweight coding agent that runs in your terminal

View on GitHub

13 documents · Updated Nov 16, 2026

docs / extensions-plugins-and-capabilities

Extensions, Plugins, and Capabilities

Overview

This area is the Codex extension surface: typed extension hooks, plugin/package discovery, built-in capability extensions, MCP client/server plumbing, and capability-specific helper crates. The central contract is codex-rs/…/lib.rs, which re-exports the host-facing API: ExtensionRegistryBuilder, ExtensionRegistry, typed lifecycle contributor traits, ExtensionData, ToolExecutor/ToolCall/ToolSpec from the tool layer, MCP types from codex-rs/…/lib.rs, and model/request interception types. Host code installs extensions by adding trait objects to ExtensionRegistryBuilder in codex-rs/…/registry.rs; the immutable registry preserves registration order and exposes contributor slices for thread, turn, prompt/world-state, MCP, turn-input, tool, model-request, message, approval, token, skill-invocation, and turn-item phases.

Extension state is explicit and scoped. codex-rs/…/state.rs stores type-erased Arc<T> attachments in ExtensionData for session, thread, turn, and step scopes; contributors communicate by inserting and reading typed values rather than holding core runtime objects. codex-rs/…/contributors.rs defines the execution shape: ThreadLifecycleContributor seeds and flushes thread state, TurnLifecycleContributor refreshes catalogs and observes turn stop/abort/error, ContextContributor adds prompt/world-state fragments, TurnInputContributor adds model-visible per-turn fragments, ToolContributor prepares step state and returns native tools, and ToolLifecycleContributor observes dispatch/start/finish/timing without owning execution. codex-rs/…/session_isolation.rs lets internal sessions opt out of inherited extensions and instructions through SessionIsolation::Isolated and supply an explicit isolated registry.

Plugin metadata is split between inert shared models and host/runtime loaders. codex-rs/…/manifest.rs defines the generic PluginManifest<Resource> shape: name/version/description/keywords, paths for skills, onboarding skill, MCP servers, apps, hooks, and optional UI/model interface metadata. codex-rs/…/provider.rs turns a manifest into an authority-bound ResolvedPlugin whose PluginResourceLocator keeps the owning environment and URI with every resource. Local plugin IDs and installed-package rules live in codex-rs/…/lib.rs; codex-rs/…/lib.rs adds public identifiers, loaded-plugin summaries, app declarations, hook-source metadata, and telemetry metadata.

codex-rs/…/lib.rs is the main plugin manager facade. Runtime loading starts in codex-rs/…/manager.rs: PluginsManager::plugins_for_config derives a cache key from effective plugin config, plugin policy, skill rules, remote-catalog state, and account identity, then calls load_plugins_from_layer_stack in codex-rs/…/loader.rs. The loader merges configured local plugins with remote-installed plugins, enforces plugin policy, loads up to eight plugins concurrently while preserving configured-name order, parses manifests, resolves skill roots, MCP server configs, app declarations, and hooks, and emits PluginLoadOutcome. Hooks can be loaded alone through load_plugin_hooks_from_layer_stack, which intentionally skips skills/MCP/apps. codex-rs/…/manifest.rs parses both legacy manifests and agent-plugin manifests, validates manifest-relative ./... paths, rejects ../absolute escapes, and maps URI manifests for executor-owned plugins. codex-rs/…/executor_provider.rs resolves selected capability roots in executor filesystems into ResolvedExecutorPlugin, keeping the exact ExecutorFileSystem used to read later plugin resources. Source-neutral cloud/executor plugin catalogs are merged in codex-rs/…/catalog.rs, where complete cloud catalogs can disable unmatched remote entries while partial catalogs preserve executor-only entries.

MCP support has two layers. codex-rs/…/lib.rs wraps the official rmcp SDK and exposes RmcpClient, transports, OAuth helpers, request cancellation, auth status, event notifications, and user verification. The implementation in codex-rs/…/rmcp_client.rs supports in-process, stdio, streamable HTTP, OAuth-managed HTTP, and access-token-only HTTP transports. It performs initialization once, stores a RunningService, lists tools/resources/templates, reads resources, calls tools, sends custom requests/notifications, opens event streams, persists/refetches OAuth tokens, applies read-only tool metadata, and routes modern request-scoped elicitation only on protocol 2026-07-28. codex-rs/…/lib.rs builds on this client to provide Codex MCP runtime/catalog/resource APIs, app-hosted server configuration, server conflict handling, connector metadata recovery, sandbox/network metadata, authorization elicitation, OAuth scope discovery, tool request metadata, and backwards-compatible Codex Apps runtime aliases.

The default hosted Apps MCP contribution is installed by codex-rs/…/lib.rs. HostedPluginRuntimeExtension contributes CODEX_APPS_MCP_SERVER_NAME using hosted_plugin_runtime_mcp_server_config when Feature::Apps is enabled and returns a remove contribution when it is not. The same crate also exposes plugin-provider installation and event-stream management. A separate MCP adapter in codex-rs/…/lib.rs binds existing message-board tools to an MCP server per caller; request metadata never selects identity, and MessageBoardMcpServer::new fixes the caller thread/path and board instance. Its detached HTTP binary in codex-rs/…/main.rs opens Codex SQLite state, validates a configured bearer token, and serves /mcp with allowed-host checks.

Built-in capability extensions register through the same extension API:

  • codex-rs/…/extension.rs installs thread lifecycle, config, prompt/world-state, turn-input, skill-invocation, turn-lifecycle telemetry, and tool contributors. It seeds SkillsSessionState/SkillsThreadState, renders available-skill catalog fragments, prepares step catalogs, injects explicit skill prompts, tracks implicit/explicit invocations, and returns namespaced skills tools from codex-rs/…/mod.rs (list, read, and discovery-v2 installations). The standalone skill library in codex-rs/…/lib.rs parses skill metadata/frontmatter, extracts explicit/implicit mentions, loads skill roots, resolves interface files, and installs embedded system skills under CODEX_HOME/skills/.system with a fingerprint marker.
  • codex-rs/…/extension.rs installs memory prompt context and optional dedicated memory tools when Feature::MemoryTool and config.memories.use_memories are enabled. It freezes the selected MemoryVersion on config changes so the prompt summary and tool namespace stay aligned. codex-rs/…/mod.rs exposes namespaced memories tools for ad-hoc note creation, listing, reading, and searching against LocalMemoriesBackend. codex-rs/…/lib.rs owns read-path helpers and memory_root; codex-rs/…/lib.rs owns the startup write pipeline, memory workspace layout, rollout summaries, raw memory file, extension resources, pruning, and symlink cleanup.
  • codex-rs/…/plugin_app.rs loads app declarations from executor-resolved plugins by reading the manifest's paths.apps through the plugin's ExecutorFileSystem and parsing it with codex_connectors::parse_plugin_app_config. Connector directory and runtime data live in codex-rs/…/lib.rs: it caches directory listings in memory and on disk for one hour, merges public and workspace connector pages, normalizes names/descriptions/install URLs, parses plugin app config, projects installed connector runtimes, stores metadata, and evaluates app tool policy.
  • codex-rs/…/extension.rs contributes a web.run-style tool when the provider supports standalone search and the step's WebSearchMode is not disabled. It copies location/filter/search-size config, chooses OpenAI/provider auth from thread state or the extension's AuthManager, and writes extension items defined in codex-rs/…/lib.rs under web.search.
  • codex-rs/…/extension.rs contributes the image_gen.imagegen tool for OpenAI-compatible providers, resolves an optional save root from config, and emits image_gen.generation items from codex-rs/…/lib.rs.
  • codex-rs/…/lib.rs registers a caller-owned QueuedItemService as a thread lifecycle contributor and spawns its external-message watcher so queued user input can be dispatched when a thread becomes idle.
  • codex-rs/…/lib.rs starts resolved agent invocations by spawning a legacy subagent thread through ThreadManager::spawn_legacy_subagent and submitting the rendered prompt as the initial user input. codex-rs/…/lib.rs installs board-backed tools over codex_message_board and selects the agent_message_board storage namespace.
  • codex-rs/…/lib.rs, codex-rs/…/lib.rs, and codex-rs/…/lib.rs cover Guardian review integration. V2 installs async scoring and synchronous approval review; V3 owns durable evidence boards in the guardian namespace; the reviewer crate owns review prompts, routing, retries, deadlines, evidence records, and review outcomes independently of the host runtime.
  • codex-rs/…/lib.rs, codex-rs/…/lib.rs, codex-rs/…/lib.rs, and codex-rs/…/lib.rs are smaller extension crates for goal tools/runtime, history-note tools, cross-environment file copy, and git attribution world-state respectively. Git attribution resolves a policy over the configured ChatGPT base URL and caches retry state in extension stores.

Other covered crates are support capabilities rather than registry-installed extensions. codex-rs/…/lib.rs and its submodules manage a dedicated V8 plugin helper process: PluginProcess::spawn launches an absolute helper path with --codex-ui-plugin-process, clears the environment, waits for the codex-ui-plugin-process/3 ready frame, frames stdin/stdout with a 1 MiB little-endian length-delimited codec, captures only the last 16 KiB of stderr, and tears down the process group or Windows job on close/drop. codex-rs/…/protocol.rs defines the narrow ABI (Initialize, Dispatch, Close; Initialized, Pending, Reply, Error, Closed) and size/quota constants. codex-rs/…/lib.rs imports external-agent MCP, hooks, memory, subagents, plugins, and sessions into Codex config. codex-rs/…/lib.rs is a bounded terminal renderer for a subset of Mermaid diagrams. codex-rs/…/lib.rs embeds default and plan collaboration prompts. codex-rs/…/lib.rs derives ExperimentalApi by generating field/variant presence checks and inventory registrations for fields marked #[experimental("reason")] or nested fields marked #[experimental(nested)].

Path routing notes for this doc:

  • codex-rs/ext/extension-api/** owns the extension API contract and registry; other codex-rs/ext/*/** crates are built-in extensions/capabilities.
  • codex-rs/plugin/**, codex-rs/core-plugin-common/**, codex-rs/core-plugins/**, and codex-rs/plugin-host/** own plugin manifests, identities, marketplaces/cache/loading, executor plugin resolution, and helper-process IPC.
  • codex-rs/codex-mcp/**, codex-rs/rmcp-client/**, and codex-rs/message-board-mcp/** own MCP runtime/client/server behavior.
  • codex-rs/skills/** and codex-rs/memories/** are lower-level skill and memory libraries used by the corresponding extension crates.
  • codex-rs/connectors/** is connector/app directory and runtime support; codex-rs/ext/connectors/** adapts plugin app declarations into the extension/plugin flow.
  • codex-rs/external-agent-migration/**, codex-rs/collaboration-mode-templates/**, codex-rs/mermaid/**, and codex-rs/codex-experimental-api-macros/** are adjacent capabilities covered here because they participate in extension/plugin-facing features or model-visible capability surfaces.

Coupling

Risks

  • codex-rs/…/process.rs clears the helper environment, requires an absolute canonical helper path, and kills the whole helper process group/job on drop. If helper startup begins depending on inherited environment variables or child processes retain stderr writers, startup can fail with only a bounded stderr tail or teardown can hang until process cleanup finishes.
  • codex-rs/…/rmcp_client.rs multiplexes shared MCP connections, OAuth refresh, recovery retries, cancellation, and request-scoped elicitation. If a call path uses cached capabilities or a stale service rather than the current RunningService, a recovered HTTP/stdout session can send tool metadata or elicitation to the wrong MCP session.
  • codex-rs/…/manager.rs caches loaded plugins by config, policy, skill rules, remote-catalog activity, and auth identity. If new plugin-affecting configuration is not included in PluginLoadCacheKey, users can see stale skills/MCP servers/apps until the cache is manually cleared.
  • codex-rs/…/loader.rs preserves configured-name order for duplicate MCP server precedence while loading plugins concurrently. If that ordered consumption is changed, the winning plugin for a duplicate server name can become nondeterministic.
  • codex-rs/…/extension.rs reads skill prompts through different authorities for host, executor, cloud, and custom sources. If a new skill source bypasses SkillToolAuthority/SkillReadContext checks, model-visible skill reads can cross environment or MCP authority boundaries.
  • codex-rs/…/extension.rs intentionally keeps the initial memory version after config changes. If this freeze is removed, a thread can render memory instructions for one layout while exposing tools against another layout, causing missing or stale memory reads.