feat: load from plugins

Author: xl-openai

codex-rs/app-server/src/codex_message_processor.rs

@@ -221,6 +221,7 @@ use codex_core::find_thread_names_by_ids;
 use codex_core::find_thread_path_by_id_str;
 use codex_core::git_info::git_diff_to_remote;
 use codex_core::mcp::collect_mcp_snapshot;
+use codex_core::mcp::configured_mcp_servers;
 use codex_core::mcp::group_tools_by_server;
 use codex_core::models_manager::collaboration_mode_presets::CollaborationModesConfig;
 use codex_core::parse_cursor;
@@ -4050,7 +4051,9 @@ impl CodexMessageProcessor {
             }
         };
 
-        let mcp_servers = match serde_json::to_value(config.mcp_servers.get()) {
+        let configured_servers =
+            configured_mcp_servers(&config, self.thread_manager.plugins_manager().as_ref());
+        let mcp_servers = match serde_json::to_value(configured_servers) {
             Ok(value) => value,
             Err(err) => {
                 let error = JSONRPCErrorError {
@@ -4111,7 +4114,9 @@ impl CodexMessageProcessor {
             timeout_secs,
         } = params;
 
-        let Some(server) = config.mcp_servers.get().get(&name) else {
+        let configured_servers =
+            configured_mcp_servers(&config, self.thread_manager.plugins_manager().as_ref());
+        let Some(server) = configured_servers.get(&name) else {
             let error = JSONRPCErrorError {
                 code: INVALID_REQUEST_ERROR_CODE,
                 message: format!("No MCP server named '{name}' found."),

codex-rs/cli/src/mcp_cmd.rs

@@ -14,6 +14,8 @@ use codex_core::config::types::McpServerTransportConfig;
 use codex_core::mcp::auth::McpOAuthLoginSupport;
 use codex_core::mcp::auth::compute_auth_statuses;
 use codex_core::mcp::auth::oauth_login_support;
+use codex_core::mcp::effective_mcp_servers;
+use codex_core::plugins::PluginsManager;
 use codex_protocol::protocol::McpAuthStatus;
 use codex_rmcp_client::delete_oauth_tokens;
 use codex_rmcp_client::perform_oauth_login;
@@ -327,10 +329,12 @@ async fn run_login(config_overrides: &CliConfigOverrides, login_args: LoginArgs)
     let config = Config::load_with_cli_overrides(overrides)
         .await
         .context("failed to load configuration")?;
+    let plugins_manager = PluginsManager::new(config.codex_home.clone());
+    let mcp_servers = effective_mcp_servers(&config, None, &plugins_manager);
 
     let LoginArgs { name, scopes } = login_args;
 
-    let Some(server) = config.mcp_servers.get().get(&name) else {
+    let Some(server) = mcp_servers.get(&name) else {
         bail!("No MCP server named '{name}' found.");
     };
 
@@ -371,12 +375,12 @@ async fn run_logout(config_overrides: &CliConfigOverrides, logout_args: LogoutAr
     let config = Config::load_with_cli_overrides(overrides)
         .await
         .context("failed to load configuration")?;
+    let plugins_manager = PluginsManager::new(config.codex_home.clone());
+    let mcp_servers = effective_mcp_servers(&config, None, &plugins_manager);
 
     let LogoutArgs { name } = logout_args;
 
-    let server = config
-        .mcp_servers
-        .get()
+    let server = mcp_servers
         .get(&name)
         .ok_or_else(|| anyhow!("No MCP server named '{name}' found in configuration."))?;
 
@@ -401,14 +405,13 @@ async fn run_list(config_overrides: &CliConfigOverrides, list_args: ListArgs) ->
     let config = Config::load_with_cli_overrides(overrides)
         .await
         .context("failed to load configuration")?;
+    let plugins_manager = PluginsManager::new(config.codex_home.clone());
+    let mcp_servers = effective_mcp_servers(&config, None, &plugins_manager);
 
-    let mut entries: Vec<_> = config.mcp_servers.iter().collect();
+    let mut entries: Vec<_> = mcp_servers.iter().collect();
     entries.sort_by(|(a, _), (b, _)| a.cmp(b));
-    let auth_statuses = compute_auth_statuses(
-        config.mcp_servers.iter(),
-        config.mcp_oauth_credentials_store_mode,
-    )
-    .await;
+    let auth_statuses =
+        compute_auth_statuses(mcp_servers.iter(), config.mcp_oauth_credentials_store_mode).await;
 
     if list_args.json {
         let json_entries: Vec<_> = entries
@@ -651,8 +654,10 @@ async fn run_get(config_overrides: &CliConfigOverrides, get_args: GetArgs) -> Re
     let config = Config::load_with_cli_overrides(overrides)
         .await
         .context("failed to load configuration")?;
+    let plugins_manager = PluginsManager::new(config.codex_home.clone());
+    let mcp_servers = effective_mcp_servers(&config, None, &plugins_manager);
 
-    let Some(server) = config.mcp_servers.get().get(&get_args.name) else {
+    let Some(server) = mcp_servers.get(&get_args.name) else {
         bail!("No MCP server named '{name}' found.", name = get_args.name);
     };
 

codex-rs/core/config.schema.json

@@ -1064,6 +1064,22 @@
       ],
       "type": "string"
     },
+    "PluginConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "path": {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "type": "object"
+    },
     "ProjectConfig": {
       "additionalProperties": false,
       "properties": {
@@ -1960,6 +1976,14 @@
     "plan_mode_reasoning_effort": {
       "$ref": "#/definitions/ReasoningEffort"
     },
+    "plugins": {
+      "additionalProperties": {
+        "$ref": "#/definitions/PluginConfig"
+      },
+      "default": {},
+      "description": "User-level plugin config entries keyed by plugin name.",
+      "type": "object"
+    },
     "profile": {
       "description": "Profile to use from the `profiles` map.",
       "type": "string"

codex-rs/core/src/codex.rs

@@ -182,6 +182,7 @@ use crate::mentions::build_skill_name_counts;
 use crate::mentions::collect_explicit_app_ids;
 use crate::mentions::collect_tool_mentions_from_messages;
 use crate::network_policy_decision::execpolicy_network_rule_amendment;
+use crate::plugins::PluginsManager;
 use crate::project_doc::get_user_instructions;
 use crate::protocol::AgentMessageContentDeltaEvent;
 use crate::protocol::AgentReasoningSectionBreakEvent;
@@ -315,6 +316,7 @@ impl Codex {
         auth_manager: Arc<AuthManager>,
         models_manager: Arc<ModelsManager>,
         skills_manager: Arc<SkillsManager>,
+        plugins_manager: Arc<PluginsManager>,
         file_watcher: Arc<FileWatcher>,
         conversation_history: InitialHistory,
         session_source: SessionSource,
@@ -326,6 +328,7 @@ impl Codex {
         let (tx_sub, rx_sub) = async_channel::bounded(SUBMISSION_CHANNEL_CAPACITY);
         let (tx_event, rx_event) = async_channel::unbounded();
 
+        let loaded_plugins = plugins_manager.plugins_for_config(&config);
         let loaded_skills = skills_manager.skills_for_config(&config);
 
         for err in &loaded_skills.errors {
@@ -335,6 +338,19 @@ impl Codex {
                 err.message
             );
         }
+        for plugin in loaded_plugins
+            .plugins
+            .iter()
+            .filter(|plugin| plugin.error.is_some())
+        {
+            if let Some(error) = plugin.error.as_deref() {
+                warn!(
+                    plugin = plugin.config_name,
+                    path = %plugin.root.display(),
+                    "failed to load plugin: {error}"
+                );
+            }
+        }
 
         if let SessionSource::SubAgent(SubAgentSource::ThreadSpawn { depth, .. }) = session_source
             && depth >= config.agent_max_depth
@@ -462,6 +478,7 @@ impl Codex {
             conversation_history,
             session_source_clone,
             skills_manager,
+            plugins_manager,
             file_watcher,
             agent_control,
         )
@@ -1062,6 +1079,7 @@ impl Session {
         initial_history: InitialHistory,
         session_source: SessionSource,
         skills_manager: Arc<SkillsManager>,
+        plugins_manager: Arc<PluginsManager>,
         file_watcher: Arc<FileWatcher>,
         agent_control: AgentControl,
     ) -> anyhow::Result<Arc<Self>> {
@@ -1144,9 +1162,11 @@ impl Session {
         let history_meta_fut = crate::message_history::history_metadata(&config);
         let auth_manager_clone = Arc::clone(&auth_manager);
         let config_for_mcp = Arc::clone(&config);
+        let plugins_manager_for_mcp = Arc::clone(&plugins_manager);
         let auth_and_mcp_fut = async move {
             let auth = auth_manager_clone.auth().await;
-            let mcp_servers = effective_mcp_servers(&config_for_mcp, auth.as_ref());
+            let mcp_servers =
+                effective_mcp_servers(&config_for_mcp, auth.as_ref(), &plugins_manager_for_mcp);
             let auth_statuses = compute_auth_statuses(
                 mcp_servers.iter(),
                 config_for_mcp.mcp_oauth_credentials_store_mode,
@@ -1394,6 +1414,7 @@ impl Session {
             tool_approvals: Mutex::new(ApprovalStore::default()),
             execve_session_approvals: RwLock::new(HashMap::new()),
             skills_manager,
+            plugins_manager,
             file_watcher,
             agent_control,
             network_proxy,
@@ -2307,6 +2328,8 @@ impl Session {
             .config_layer_stack
             .with_user_config(&config_toml_path, user_config);
         state.session_configuration.original_config_do_not_use = Arc::new(config);
+        self.services.skills_manager.clear_cache();
+        self.services.plugins_manager.clear_cache();
     }
 
     pub(crate) async fn new_default_turn_with_sub_id(&self, sub_id: String) -> Arc<TurnContext> {
@@ -4120,7 +4143,11 @@ mod handlers {
     pub async fn list_mcp_tools(sess: &Session, config: &Arc<Config>, sub_id: String) {
         let mcp_connection_manager = sess.services.mcp_connection_manager.read().await;
         let auth = sess.services.auth_manager.auth().await;
-        let mcp_servers = effective_mcp_servers(config, auth.as_ref());
+        let mcp_servers = effective_mcp_servers(
+            config,
+            auth.as_ref(),
+            sess.services.plugins_manager.as_ref(),
+        );
         let snapshot = collect_mcp_snapshot_from_manager(
             &mcp_connection_manager,
             compute_auth_statuses(mcp_servers.iter(), config.mcp_oauth_credentials_store_mode)
@@ -8280,6 +8307,11 @@ mod tests {
 
         let (tx_event, _rx_event) = async_channel::unbounded();
         let (agent_status_tx, _agent_status_rx) = watch::channel(AgentStatus::PendingInit);
+        let plugins_manager = Arc::new(PluginsManager::new(config.codex_home.clone()));
+        let skills_manager = Arc::new(SkillsManager::new(
+            config.codex_home.clone(),
+            Arc::clone(&plugins_manager),
+        ));
         let result = Session::new(
             session_configuration,
             Arc::clone(&config),
@@ -8290,7 +8322,8 @@ mod tests {
             agent_status_tx,
             InitialHistory::New,
             SessionSource::Exec,
-            Arc::new(SkillsManager::new(config.codex_home.clone())),
+            skills_manager,
+            plugins_manager,
             Arc::new(FileWatcher::noop()),
             AgentControl::default(),
         )
@@ -8371,7 +8404,11 @@ mod tests {
         );
 
         let state = SessionState::new(session_configuration.clone());
-        let skills_manager = Arc::new(SkillsManager::new(config.codex_home.clone()));
+        let plugins_manager = Arc::new(PluginsManager::new(config.codex_home.clone()));
+        let skills_manager = Arc::new(SkillsManager::new(
+            config.codex_home.clone(),
+            Arc::clone(&plugins_manager),
+        ));
         let network_approval = Arc::new(NetworkApprovalService::default());
 
         let file_watcher = Arc::new(FileWatcher::noop());
@@ -8405,6 +8442,7 @@ mod tests {
             tool_approvals: Mutex::new(ApprovalStore::default()),
             execve_session_approvals: RwLock::new(HashMap::new()),
             skills_manager,
+            plugins_manager,
             file_watcher,
             agent_control,
             network_proxy: None,
@@ -8530,7 +8568,11 @@ mod tests {
         );
 
         let state = SessionState::new(session_configuration.clone());
-        let skills_manager = Arc::new(SkillsManager::new(config.codex_home.clone()));
+        let plugins_manager = Arc::new(PluginsManager::new(config.codex_home.clone()));
+        let skills_manager = Arc::new(SkillsManager::new(
+            config.codex_home.clone(),
+            Arc::clone(&plugins_manager),
+        ));
         let network_approval = Arc::new(NetworkApprovalService::default());
 
         let file_watcher = Arc::new(FileWatcher::noop());
@@ -8564,6 +8606,7 @@ mod tests {
             tool_approvals: Mutex::new(ApprovalStore::default()),
             execve_session_approvals: RwLock::new(HashMap::new()),
             skills_manager,
+            plugins_manager,
             file_watcher,
             agent_control,
             network_proxy: None,

codex-rs/core/src/codex_delegate.rs

@@ -53,6 +53,7 @@ pub(crate) async fn run_codex_thread_interactive(
         auth_manager,
         models_manager,
         Arc::clone(&parent_session.services.skills_manager),
+        Arc::clone(&parent_session.services.plugins_manager),
         Arc::clone(&parent_session.services.file_watcher),
         initial_history.unwrap_or(InitialHistory::New),
         SessionSource::SubAgent(SubAgentSource::Review),

codex-rs/core/src/config/mod.rs

@@ -15,6 +15,7 @@ use crate::config::types::Notifications;
 use crate::config::types::OtelConfig;
 use crate::config::types::OtelConfigToml;
 use crate::config::types::OtelExporterKind;
+use crate::config::types::PluginConfig;
 use crate::config::types::SandboxWorkspaceWrite;
 use crate::config::types::ShellEnvironmentPolicy;
 use crate::config::types::ShellEnvironmentPolicyToml;
@@ -1203,6 +1204,10 @@ pub struct ConfigToml {
     /// User-level skill config entries keyed by SKILL.md path.
     pub skills: Option<SkillsConfig>,
 
+    /// User-level plugin config entries keyed by plugin name.
+    #[serde(default)]
+    pub plugins: HashMap<String, PluginConfig>,
+
     /// Centralized feature flags (new). Prefer this over individual toggles.
     #[serde(default)]
     // Injects known feature keys into the schema and forbids unknown keys.

codex-rs/core/src/config/types.rs

@@ -727,6 +727,14 @@ pub struct SkillConfig {
     pub enabled: bool,
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct PluginConfig {
+    pub path: AbsolutePathBuf,
+    #[serde(default = "default_enabled")]
+    pub enabled: bool,
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
 #[schemars(deny_unknown_fields)]
 pub struct SkillsConfig {

codex-rs/core/src/file_watcher.rs

@@ -23,7 +23,7 @@ use tokio::time::sleep_until;
 use tracing::warn;
 
 use crate::config::Config;
-use crate::skills::loader::skill_roots_from_layer_stack_with_agents;
+use crate::skills::loader::skill_roots;
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum FileWatcherEvent {
@@ -145,7 +145,7 @@ impl FileWatcher {
 
     pub(crate) fn register_config(self: &Arc<Self>, config: &Config) -> WatchRegistration {
         let deduped_roots: HashSet<PathBuf> =
-            skill_roots_from_layer_stack_with_agents(&config.config_layer_stack, &config.cwd)
+            skill_roots(&config.config_layer_stack, &config.cwd, Vec::new())
                 .into_iter()
                 .map(|root| root.path)
                 .collect();

codex-rs/core/src/lib.rs

@@ -56,6 +56,7 @@ mod message_history;
 mod model_provider_info;
 pub mod path_utils;
 pub mod personality_migration;
+pub mod plugins;
 mod sandbox_tags;
 pub mod sandboxing;
 mod session_prefix;