Plugins System

Relevant source files

• codex-rs/app-server-protocol/schema/json/v2/PluginListResponse.json
• codex-rs/app-server-protocol/schema/json/v2/PluginReadResponse.json
• codex-rs/app-server-protocol/schema/json/v2/PluginShareListResponse.json
• codex-rs/app-server-protocol/src/protocol/v2/plugin.rs
• codex-rs/app-server/src/request_processors/plugins.rs
• codex-rs/app-server/tests/suite/v2/plugin_install.rs
• codex-rs/app-server/tests/suite/v2/plugin_list.rs
• codex-rs/app-server/tests/suite/v2/plugin_read.rs
• codex-rs/app-server/tests/suite/v2/plugin_share.rs
• codex-rs/cli/src/marketplace_cmd.rs
• codex-rs/cli/src/plugin_cmd.rs
• codex-rs/cli/tests/marketplace_add.rs
• codex-rs/cli/tests/marketplace_remove.rs
• codex-rs/cli/tests/marketplace_upgrade.rs
• codex-rs/cli/tests/plugin_cli.rs
• codex-rs/cli/tests/update.rs
• codex-rs/config/src/marketplace_edit.rs
• codex-rs/core-plugins/Cargo.toml
• codex-rs/core-plugins/src/agent_plugin_manifest.rs
• codex-rs/core-plugins/src/agent_plugin_manifest_tests.rs
• codex-rs/core-plugins/src/installed_marketplaces.rs
• codex-rs/core-plugins/src/lib.rs
• codex-rs/core-plugins/src/loader.rs
• codex-rs/core-plugins/src/loader_tests.rs
• codex-rs/core-plugins/src/manager.rs
• codex-rs/core-plugins/src/manager_tests.rs
• codex-rs/core-plugins/src/manifest.rs
• codex-rs/core-plugins/src/marketplace_policy.rs
• codex-rs/core-plugins/src/marketplace_policy_tests.rs
• codex-rs/core-plugins/src/marketplace_upgrade_tests.rs
• codex-rs/core-plugins/src/remote.rs
• codex-rs/core-plugins/src/remote/share.rs
• codex-rs/core-plugins/src/remote/share/tests.rs
• codex-rs/core-plugins/src/remote_tests.rs
• codex-rs/core-plugins/src/test_support.rs
• codex-rs/core-plugins/src/tool_suggest_metadata.rs
• codex-rs/core-skills/src/loader.rs
• codex-rs/core-skills/src/loader/discovery.rs
• codex-rs/core-skills/src/loader/environment.rs
• codex-rs/core-skills/src/loader_tests.rs
• codex-rs/core-skills/src/root_loader.rs
• codex-rs/core-skills/src/service.rs
• codex-rs/core-skills/src/service_tests.rs
• codex-rs/core-skills/tests/environment_loader.rs
• codex-rs/ext/skills/tests/executor_file_system_authority.rs
• codex-rs/plugin/src/load_outcome.rs
• codex-rs/utils/plugins/src/lib.rs
• codex-rs/utils/plugins/src/plugin_namespace.rs

The Plugins System provides an extensibility framework for Codex, allowing the discovery, installation, and execution of third-party capabilities. Plugins bundle multiple entities, including Skills (natural language instructions), MCP Servers (external tool providers), App Connectors (integrations with web services), and Hooks (automated session events) [codex-rs/core-plugins/src/remote.rs:171-175] [codex-rs/core-plugins/src/loader.rs:65-68].

Overview and Marketplace

Plugins are distributed via Marketplaces, which are defined by a marketplace.json manifest file [codex-rs/app-server/tests/suite/v2/plugin_list.rs:106-108] [codex-rs/core-plugins/src/marketplace.rs:1-20]. Codex supports local marketplaces (often in a repository's .agents/plugins/ or .claude-plugin/ directory) and remote marketplaces managed via the ChatGPT backend [codex-rs/app-server/tests/suite/v2/plugin_list.rs:51-55] [codex-rs/core-plugins/src/remote.rs:77-84].

Plugin Discovery and Activation

The system resolves plugins by looking up their metadata in configured marketplaces and matching them against local installation state.

Plugin Activation Flow

Sources: [codex-rs/core-plugins/src/manager.rs:122-130], [codex-rs/core-plugins/src/loader.rs:122-150], [codex-rs/core-plugins/src/remote.rs:171-185], [codex-rs/core-plugins/src/store.rs:62]

PluginsManager and App Server Integration

The PluginsManager coordinates plugin operations, tracking authentication modes and managing the lifecycle of both local and remote plugins [codex-rs/core-plugins/src/manager.rs:122] [codex-rs/core-plugins/src/manager_tests.rs:120-139]. The PluginRequestProcessor in the app-server exposes these capabilities via JSON-RPC endpoints like plugin/list, plugin/install, and plugin/share/save [codex-rs/app-server/src/request_processors/plugins.rs:35-44].

Key Structures

Struct	Description
LoadedPlugin	Represents a plugin validated and loaded from disk, containing its skills, hooks, and MCP servers [codex-rs/core-plugins/src/lib.rs:40] [codex-rs/core-plugins/src/loader.rs:38].
PluginsManager	The primary orchestrator for listing, installing, and loading plugins across local and remote sources [codex-rs/core-plugins/src/manager.rs:67].
PluginStore	Manages the physical files in the plugins cache directory and versioning [codex-rs/core-plugins/src/store.rs:62] [codex-rs/core-plugins/src/loader.rs:125].
RemoteInstalledPlugin	Detailed metadata for plugins hosted on remote services, including bundle versions and auth policies [codex-rs/core-plugins/src/remote.rs:170-185].
PluginSummary	Protocol-level summary used for UI display in marketplace listings [codex-rs/app-server/src/request_processors/plugins.rs:166-181].

Sources: [codex-rs/core-plugins/src/lib.rs:40-67], [codex-rs/core-plugins/src/remote.rs:170-185], [codex-rs/app-server/src/request_processors/plugins.rs:35-181]

Plugin Installation and Storage

Plugins are versioned and stored in a local cache directory to ensure session stability and offline availability.

Storage Hierarchy

The PluginStore enforces a directory structure within the Codex home:

• Cache Root: Defined by PLUGINS_CACHE_DIR (plugins/cache/) [codex-rs/core-plugins/src/store.rs:4] [codex-rs/core-plugins/src/remote.rs:4].
• Structure: plugins/cache/{marketplace}/{plugin_name}/{version}/ - Contains the immutable plugin bundle [codex-rs/app-server/tests/suite/v2/plugin_install.rs:209-211].
• Manifests: Every plugin must contain a plugin.json manifest (discovered via find_plugin_manifest_path) for metadata and capability discovery [codex-rs/core-plugins/src/loader.rs:52] [codex-rs/core-plugins/src/manifest.rs:9].

Installation Workflow

1. Request: Triggered via plugin/install with a marketplacePath or remoteMarketplaceName [codex-rs/app-server/tests/suite/v2/plugin_install.rs:111-116].
2. Validation: The system ensures exactly one source is provided and validates the plugin ID against the marketplace [codex-rs/app-server/tests/suite/v2/plugin_install.rs:134-165] [codex-rs/core-plugins/src/marketplace.rs:33-34].
3. Download/Materialization: For remote plugins, a .tar.gz bundle is downloaded via the ChatGPT API, verified, and extracted to the cache [codex-rs/app-server/tests/suite/v2/plugin_install.rs:206-218].
4. Registration: The plugin is registered in the user's config.toml under the [plugins] table, enabling it for future sessions [codex-rs/core-plugins/src/manager_tests.rs:154-156] [codex-rs/app-server/tests/suite/v2/plugin_list.rs:162-171].

Sources: [codex-rs/app-server/tests/suite/v2/plugin_install.rs:72-218], [codex-rs/core-plugins/src/remote.rs:4], [codex-rs/core-plugins/src/manager.rs:31-33]

Remote Plugins and Sharing

Codex supports a "Remote Plugin" feature that allows syncing plugins with the ChatGPT ecosystem [codex-rs/core-plugins/src/remote.rs:77-90].

Remote Marketplace Sync

The system syncs with global and workspace-specific remote marketplaces:

• Marketplaces: Includes openai-curated-remote, created-by-me-remote, workspace-directory, and various shared scopes [codex-rs/core-plugins/src/remote.rs:77-84].
• Sync Logic: sync_remote_installed_plugin_bundles_once ensures that plugins marked as "installed" in the remote account have their bundles present locally [codex-rs/core-plugins/src/remote.rs:59].
• Cache Management: RemotePluginCacheMutationGuard prevents race conditions during concurrent sync or installation operations [codex-rs/core-plugins/src/remote.rs:55-57].

Plugin Sharing

Users can share local plugins by uploading them to the remote catalog via the app-server:

1. Discoverability: Plugins can be shared with specific discoverability levels (e.g., Public, Unlisted) [codex-rs/core-plugins/src/remote.rs:61] [codex-rs/app-server/src/request_processors/plugins.rs:144-164].
2. Principals: Sharing can be targeted at specific users or groups with Reader or Editor roles [codex-rs/core-plugins/src/remote.rs:62-67] [codex-rs/app-server/src/request_processors/plugins.rs:8-9].
3. Persistence: save_remote_plugin_share handles the bundle upload and registration of the share on the remote service [codex-rs/core-plugins/src/remote.rs:74].

Sources: [codex-rs/core-plugins/src/remote.rs:45-90], [codex-rs/app-server/src/request_processors/plugins.rs:124-164]

Session Injection and Entity Mapping

During session initialization, the PluginsManager provides the necessary injections to the core agent and its tool registry.

Plugin Entity Mapping

Sources: [codex-rs/core-plugins/src/manager.rs:67], [codex-rs/core-plugins/src/loader.rs:122-185], [codex-rs/core-plugins/src/discoverable.rs:50], [codex-rs/core-plugins/src/lib.rs:40-41]

Injection Types

• Tool Suggestions: ToolSuggestDiscoverablePlugin identifies uninstalled plugins from an allowlist (e.g., github@openai-curated) to suggest to the user based on context [codex-rs/core-plugins/src/discoverable.rs:50] [codex-rs/core-plugins/src/manager.rs:93-95].
• Skills Injection: load_plugin_skills extracts natural language capabilities from the plugin's skills/ directory and registers them with the SkillsService [codex-rs/core-plugins/src/loader.rs:13] [codex-rs/core-plugins/src/manager_tests.rs:9].
• Hook Dispatch: load_plugin_hooks identifies automated triggers (e.g., PreToolUse) defined in the plugin's manifest for session event interception [codex-rs/core-plugins/src/loader.rs:10] [codex-rs/core-plugins/src/loader.rs:74-77].
• MCP Servers: Plugin-defined MCP servers are loaded via load_plugin_mcp_servers_from_manifest and routed through the McpConnectionManager [codex-rs/core-plugins/src/loader.rs:12] [codex-rs/app-server/tests/suite/v2/plugin_read.rs:204-217].

Sources: [codex-rs/core-plugins/src/discoverable.rs:1-50], [codex-rs/core-plugins/src/loader.rs:1-190], [codex-rs/core-plugins/src/manager_tests.rs:1-139]