Optional Companion Surfaces for Codex Plugins: Web, Mobile, and Desktop Configuration

Codex plugins support three optional companion surfaces—web, mobile, and desktop—declared in the .codex-plugin/plugin.json manifest to expose additional user-interface fronts beyond the core Codex experience.

The openai/plugins repository defines the Codex plugin specification, where each plugin declares its capabilities through a manifest file located at .codex-plugin/plugin.json. One critical configuration is the optionalCompanionSurfaces field, which specifies which alternative UI surfaces the plugin can leverage across browser, mobile, and desktop environments.

What Are Optional Companion Surfaces?

Optional companion surfaces allow a Codex plugin to expose additional user-interface fronts beyond the standard chat-based Codex experience. According to the repository's top-level README.md, the plugin manifest includes optional companion surfaces that enable the plugin to launch specialized interfaces tailored to specific platforms.

When declared, these surfaces let the Codex client know that the plugin can render content in alternative environments, such as popping out a full web dashboard or launching a native mobile view.

Supported Companion Surface Types

The Codex specification recognizes three distinct surface types. Each value in the optionalCompanionSurfaces array must be one of the following strings:

Web Surface

The web surface indicates that the plugin provides a browser-based UI. This interface can be rendered within an in-app web view or launched in an external browser window. Plugins using this surface typically host supplementary dashboards, configuration panels, or rich media experiences that extend beyond text-based interactions.

Mobile Surface

The mobile surface signals that the plugin includes a native mobile interface optimized for iOS or Android clients. When declared, the Codex mobile client can launch this surface to provide touch-optimized controls or device-specific functionality that the standard chat interface cannot accommodate.

Desktop Surface

The desktop surface denotes a native desktop UI for Windows, macOS, or Linux. This allows plugins to spawn standalone application windows or system tray utilities when running inside the Codex desktop application, enabling deeper OS integration.

Configuring the Manifest

Each plugin defines its supported surfaces in the optionalCompanionSurfaces array within its manifest file. The repository structure places this configuration at plugins/<plugin-name>/.codex-plugin/plugin.json.

{
  "name": "example-plugin",
  "description": "An example Codex plugin with multiple surfaces",
  "optionalCompanionSurfaces": ["web", "mobile"]
}

A plugin may implement any combination of these surfaces, or omit the field entirely if it relies solely on the core Codex chat interface. The manifest validator checks that all entries in the array are valid surface type strings.

Runtime Detection in Plugin Code

Plugin logic can inspect the declared surfaces at runtime to conditionally launch appropriate UIs. As shown in skill implementations referencing the manifest configuration, you can check for surface availability using standard array methods.

// Checking surface availability in plugin skill logic
if (plugin.optionalCompanionSurfaces.includes('web')) {
  // Launch web dashboard in browser view
  openWebInterface();
}

if (plugin.optionalCompanionSurfaces.includes('desktop')) {
  // Open native desktop window
  createDesktopWindow();
}

The SKILL.md files within individual plugin directories often reference these surface declarations to document when and how each interface should be invoked.

Summary

• Three surface types: Codex plugins support web, mobile, and desktop optional companion surfaces.
• Manifest location: Declare supported surfaces in .codex-plugin/plugin.json using the optionalCompanionSurfaces array.
• Optional declaration: Plugins may support any combination of surfaces, or none at all, depending on use case requirements.
• Runtime inspection: Plugin code checks the optionalCompanionSurfaces array to determine which UI fronts to launch.

Frequently Asked Questions

What configuration file defines optional companion surfaces for a Codex plugin?

The .codex-plugin/plugin.json file in each plugin's root directory defines optional companion surfaces using the optionalCompanionSurfaces field. According to the repository structure, this manifest sits at plugins/<plugin-name>/.codex-plugin/plugin.json.

Can a Codex plugin support multiple companion surfaces simultaneously?

Yes. The optionalCompanionSurfaces field accepts an array of strings, allowing a single plugin to declare support for web, mobile, and desktop surfaces in any combination. The Codex client selects the appropriate surface based on the current platform and user context.

Are companion surfaces required for all Codex plugins?

No. The optionalCompanionSurfaces field is entirely optional. Plugins that operate purely through the standard chat interface can omit this field from their manifest. The repository documentation notes that these surfaces are explicitly optional extensions to the core plugin experience.

How do I check which surfaces are available at runtime?

Access the optionalCompanionSurfaces property on the plugin object and use array methods like .includes() to test for specific surface types. This allows conditional logic to launch web views, mobile screens, or desktop windows only when the manifest declares support for those platforms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}