Support detect and import MCP, Subagents, hooks, commands from external by alexsong-oai · Pull Request #19949 · openai/codex

alexsong-oai · 2026-04-28T08:05:28Z

Why

This PR expands the migration path so Codex can detect and import MCP server config, hooks, commands, and subagents configs in a Codex-native shape.

What changed

Added a codex-external-agent-migration crate that owns conversion logic for external-agent MCP servers, hooks, commands, and subagents.
Extended the app-server external-agent config detection/import API with migration item types for MCP server config, hooks, commands, and subagents.

Migration strategy

The migration is intentionally conservative: Codex only imports external-agent config that can be represented safely in Codex today. Unsupported or ambiguous config is skipped instead of being partially translated into behavior that may not match the source system.

MCP servers: import supported stdio and HTTP MCP server definitions into mcp_servers. Disabled servers and servers filtered out by source enabledMcpjsonServers / disabledMcpjsonServers are skipped. Project-scoped MCP entries from .claude.json are included when they match the repo path.
Hooks: import only supported command hooks into .codex/hooks.json. Unsupported hook features such as conditional groups, async handlers, prompt/http hooks, or unknown fields are skipped. Referenced hook scripts are copied into .codex/hooks/, preserving any existing target scripts.
Commands: import supported external commands as Codex skills under .agents/skills/source-command-*. Commands that rely on source runtime expansion such as $ARGUMENTS, $1, @file references, shell interpolation, or colliding generated names are skipped.
Subagents: import valid subagent Markdown files into .codex/agents/*.toml when they have the minimum Codex agent fields. Source model names are not migrated, so imported agents keep the user’s Codex default model; compatible reasoning effort and sandbox mode are migrated when present.
Skills and project guidance: copy missing skill directories into .agents/skills and migrate CLAUDE.md guidance into AGENTS.md, rewriting source-agent terminology to Codex terminology where appropriate.
Detection details: detected migration items include lightweight details for UI preview, such as MCP server names, hook event names, generated command skill names, and subagent names. Import still recomputes from disk instead of trusting details as the source of truth.
Adds focused coverage for the new migration behavior and app-server import flow.

Verification

cargo test -p codex-external-agent-migration
cargo test -p codex-hooks
cargo test -p codex-app-server external_agent_config
just bazel-lock-check

alexsong-oai · 2026-04-28T08:05:36Z

@codex review

alexsong-oai · 2026-04-28T08:16:08Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e0fb610fff

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-28T08:30:41Z

+fn append_convertible_hook_groups(settings: &JsonValue, migration: &mut HookMigration) {
+    let Some(hooks_config) = settings.get("hooks").and_then(JsonValue::as_object) else {
+        return;


Honor disableAllHooks when importing hooks

Hook migration ignores the source disableAllHooks flag and still imports active hook handlers from hooks. That changes behavior: users who explicitly disabled hooks in external config will get hooks enabled after migration. Detection/import should skip hook migration (or preserve disabled state) when this flag is true.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-28T08:30:41Z

+fn command_skill_name(source_commands: &Path, source_file: &Path) -> String {
+    slugify_name(&format!(
+        "{COMMAND_SKILL_PREFIX}-{}",
+        command_source_name(source_commands, source_file)
+    ))


Disambiguate colliding command skill slugs

command_skill_name normalizes paths through slugify_name, so different commands can collapse to the same skill directory (e.g. foo_bar.md and foo-bar.md). import_commands treats target_dir.exists() as already migrated and silently skips later collisions, losing commands. Use a collision-safe naming scheme or fail with an explicit error.

Useful? React with 👍 / 👎.

Commands with name collisions will be ignored.

alexsong-oai · 2026-04-28T18:01:03Z

@codex review

chatgpt-codex-connector

💡 Codex Review

codex/codex-rs/app-server/src/config/external_agent_config.rs

Lines 236 to 240 in 161389c

    
           let source_settings = repo_root.map_or_else( 
        
               || self.external_agent_home.join("settings.json"), 
        
               |repo_root| repo_root.join(EXTERNAL_AGENT_DIR).join("settings.json"), 
        
           ); 
        
           let settings = read_external_settings(&source_settings)?;

Read MCP allow/deny lists from settings.local.json

MCP migration loads only .claude/settings.json for enabledMcpjsonServers/disabledMcpjsonServers. Those are hierarchical settings, and .claude/settings.local.json can override them. Ignoring local overrides produces wrong enabled=false decisions and incorrect detect/import results.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

# Conflicts: # codex-rs/app-server-protocol/schema/json/ClientRequest.json # codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json # codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json # codex-rs/app-server-protocol/schema/json/v2/ExternalAgentConfigDetectResponse.json # codex-rs/app-server-protocol/schema/json/v2/ExternalAgentConfigImportParams.json # codex-rs/app-server-protocol/schema/typescript/v2/ExternalAgentConfigMigrationItemType.ts # codex-rs/app-server-protocol/src/protocol/v2.rs # codex-rs/app-server/src/config/external_agent_config.rs # codex-rs/app-server/src/external_agent_config_api.rs

alexsong-oai · 2026-04-28T20:53:41Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c0508e55d0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

alexsong-oai · 2026-04-28T22:34:28Z

@codex review

chatgpt-codex-connector

💡 Codex Review

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

Lines 1135 to 1146 in 66755e8

    
           let has_plugin_imports = params.migration_items.iter().any(|item| { 
        
               matches!( 
        
                   item.item_type, 
        
                   ExternalAgentConfigMigrationItemType::Plugins 
        
               ) 
        
           }); 
        
           let pending_session_imports = self 
        
               .external_agent_config_api 
        
               .prepare_pending_session_imports(&params)?; 
        
           let pending_plugin_imports = self.external_agent_config_api.import(params).await?; 
        
           if has_plugin_imports { 
        
               self.handle_config_mutation().await;

Refresh config after non-plugin migration imports

handle_external_agent_config_import() only treats Plugins as config-mutating. New import types (notably McpServerConfig and Hooks) update .codex/config.toml / hooks.json, but handle_config_mutation() is skipped, so running sessions can keep stale configuration until restart.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

alexsong-oai · 2026-04-28T23:02:35Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5cab4cfa4a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

alexsong-oai · 2026-04-29T00:15:19Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0762f5fcff

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-29T00:39:11Z

+        JsonValue::Bool(value) => Some(value.to_string()),
+        JsonValue::Number(value) => Some(value.to_string()),


Reject non-string MCP command/url values

json_string coerces booleans and numbers into strings, and mcp_server_toml_table accepts that output for MCP command/url. Invalid source config like { "command": true } is migrated as command = "true" instead of being skipped, creating unusable MCP entries and violating the commit’s conservative-import behavior.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-29T00:39:12Z

+
+    let enabled_servers = settings
+        .and_then(|settings| settings.get("enabledMcpjsonServers"))
+        .map(json_string_vec)


Ignore non-string MCP allow/deny list entries

enabledMcpjsonServers and disabledMcpjsonServers are parsed through json_string_vec, which stringifies booleans/numbers. A malformed value like enabledMcpjsonServers: true creates a non-empty allow-list ("true"), causing mcp_server_is_disabled to filter out every real server. Non-string entries should be ignored, not treated as server names.

Useful? React with 👍 / 👎.

Support detect and import MCP, Subagents, hooks, commands from external

b56f33c

minor

e0fb610

u

74fbb0b

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

address cmts

161389c

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

alexsong-oai added 4 commits April 28, 2026 12:22

Tighten external agent migration imports

36118cc

Move external agent migration into crate

4122ace

move to crate

c0508e5

alexsong-oai requested review from baumann-oai and xl-openai April 28, 2026 20:51

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread codex-rs/external-agent-migration/src/lib.rs

Comment thread codex-rs/app-server/src/config/external_agent_config.rs

Comment thread codex-rs/external-agent-migration/src/lib.rs

alexsong-oai added 3 commits April 28, 2026 14:11

address cmts

d430ec0

add detail and address cmts

90692e6

fix

66755e8

xl-openai approved these changes Apr 28, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread codex-rs/app-server/src/config/external_agent_config.rs

Comment thread codex-rs/external-agent-migration/src/lib.rs Outdated

Comment thread codex-rs/external-agent-migration/src/lib.rs

address cmts

5cab4cf

chatgpt-codex-connector Bot reviewed Apr 28, 2026

View reviewed changes

Comment thread codex-rs/app-server/src/message_processor.rs

Comment thread codex-rs/external-agent-migration/src/lib.rs

Comment thread codex-rs/external-agent-migration/src/lib.rs

refresh

684aa8d

alexsong-oai enabled auto-merge (squash) April 28, 2026 23:21

alexsong-oai added 2 commits April 28, 2026 17:04

fix tests

855b931

update schema

0762f5f

chatgpt-codex-connector Bot reviewed Apr 29, 2026

View reviewed changes

alexsong-oai merged commit cb8b1bb into main Apr 29, 2026
28 checks passed

alexsong-oai deleted the alexs/extend-migrate branch April 29, 2026 00:45

github-actions Bot locked and limited conversation to collaborators Apr 29, 2026

	let source_settings = repo_root.map_or_else(
	\|\| self.external_agent_home.join("settings.json"),
	\|repo_root\| repo_root.join(EXTERNAL_AGENT_DIR).join("settings.json"),
	);
	let settings = read_external_settings(&source_settings)?;

	let has_plugin_imports = params.migration_items.iter().any(\|item\| {
	matches!(
	item.item_type,
	ExternalAgentConfigMigrationItemType::Plugins
	)
	});
	let pending_session_imports = self
	.external_agent_config_api
	.prepare_pending_session_imports(&params)?;
	let pending_plugin_imports = self.external_agent_config_api.import(params).await?;
	if has_plugin_imports {
	self.handle_config_mutation().await;

		JsonValue::Bool(value) => Some(value.to_string()),
		JsonValue::Number(value) => Some(value.to_string()),

Conversation

alexsong-oai commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What changed

Migration strategy

Verification

Uh oh!

alexsong-oai commented Apr 28, 2026

Uh oh!

alexsong-oai commented Apr 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

alexsong-oai Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

alexsong-oai Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alexsong-oai commented Apr 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexsong-oai commented Apr 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexsong-oai commented Apr 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexsong-oai commented Apr 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexsong-oai commented Apr 29, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

alexsong-oai commented Apr 28, 2026 •

edited

Loading