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

> Discover optional companion surfaces like web, mobile, and desktop for Codex plugins. Enhance your plugin's user interface beyond the core Codex experience with custom manifest declarations.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: architecture
- Published: 2026-09-12

---

**Codex plugins support three optional companion surfaces—`web`, `mobile`, and `desktop`—declared in the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`.

```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.

```javascript
// 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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.