Understanding the CLAUDEPLUGINDATA Environment Variable in OpenAI Codex Plugin CC

The CLAUDEPLUGINDATA environment variable supplies a Base64-encoded JSON manifest to the Codex plugin at startup, eliminating the need for external configuration files in serverless and containerized deployments.

The openai/codex-plugin-cc repository uses this environment variable to pass the Claude-compatible plugin manifest directly to the runtime. When the plugin process initializes, it reads this variable to register the plugin's endpoints, authentication methods, and tool definitions with the Claude API framework.

What CLAUDEPLUGINDATA Contains

The variable stores a Base64-encoded JSON string representing the complete plugin manifest. This manifest describes:

• The plugin's name, description, and version
• HTTP endpoints that Claude may invoke (GET/POST routes with request/response schemas)
• Authentication configuration (API keys, bearer tokens, or other security schemes)
• Additional tool definitions available for Claude to call

By encoding this data into an environment variable, the plugin supports deployment scenarios where filesystem access is restricted or undesirable, such as AWS Lambda, Docker containers, or CI/CD pipelines.

Implementation in the Source Code

According to the openai/codex-plugin-cc source code, the plugin reads CLAUDEPLUGINDATA during the initialization phase. In plugins/codex/scripts/lib/utils/environment.js, the runtime decodes and parses this variable to extract the manifest configuration.

The loadClaudePluginData() function handles this process:

// plugins/codex/scripts/lib/utils/environment.js (simplified)
function loadClaudePluginData() {
  const encoded = process.env.CLAUDEPLUGINDATA;
  if (!encoded) {
    throw new Error('CLAUDEPLUGINDATA not set');
  }
  const json = Buffer.from(encoded, 'base64').toString('utf8');
  return JSON.parse(json);
}

// Initialization in main.js
const pluginManifest = loadClaudePluginData();
claude.registerPlugin(pluginManifest);

This pattern ensures the plugin fails fast with a clear error message if the required configuration is missing.

Step-by-Step Deployment Workflow

Setting up the variable follows a four-step process:

1. Generate the plugin manifest as a JSON file following the Claude plugin specification
2. Encode the JSON content using Base64 encoding
3. Export the encoded string as the CLAUDEPLUGINDATA environment variable
4. Launch the plugin server, which automatically decodes and registers the manifest

Practical Example

Create and encode a manifest:

# Create manifest.json

cat <<EOF > manifest.json
{
  "name": "MyPlugin",
  "description": "Demo plugin for Claude",
  "version": "1.0.0",
  "endpoints": [
    {
      "path": "/search",
      "method": "POST",
      "request": { "type": "object", "properties": { "query": { "type": "string" } } },
      "response": { "type": "object", "properties": { "results": { "type": "array" } } }
    }
  ]
}
EOF

# Encode and set environment variable

export CLAUDEPLUGINDATA=$(cat manifest.json | base64 -w0)

# Start the plugin

node ./plugins/codex/scripts/main.js

Key Repository Files

The implementation spans several critical files:

• plugins/codex/scripts/lib/utils/environment.js: Contains the loadClaudePluginData() function that reads and decodes the environment variable
• plugins/codex/scripts/lib/auth/constants.js: Defines authentication-related constants referenced by the manifest parser
• dist/plugin.mjs: The compiled entry point that invokes the manifest loader during startup
• test/plugin.test.js: Unit tests verifying correct parsing of the environment variable

Summary

• CLAUDEPLUGINDATA is a Base64-encoded JSON environment variable required by the openai/codex-plugin-cc runtime
• It replaces the need for a physical manifest.json file, enabling serverless deployments
• The loadClaudePluginData() function in environment.js handles decoding and validation
• The manifest must conform to Claude's plugin specification, defining endpoints and authentication schemes

Frequently Asked Questions

What happens if CLAUDEPLUGINDATA is not set?

The plugin will throw an explicit error during startup. The loadClaudePluginData() function checks for the variable's presence and throws 'CLAUDEPLUGINDATA not set' if it is missing or empty, preventing the server from starting in an unconfigured state.

Why use Base64 encoding for the manifest?

Base64 encoding ensures the JSON manifest can be safely passed through environment variables without issues related to special characters, newlines, or shell interpretation. This encoding method preserves the exact byte sequence of the JSON configuration across different deployment platforms and shell environments.

Can I use a regular manifest.json file instead?

While the openai/codex-plugin-cc repository is designed to prioritize the CLAUDEPLUGINDATA environment variable for flexibility, the implementation in plugins/codex/scripts/lib/utils/environment.js specifically expects this variable. To use a file-based approach, you would need to modify the loadClaudePluginData() function to read from the filesystem and encode the contents before parsing.

Where can I find the schema for the manifest JSON?

The manifest must follow the Claude plugin specification, which defines required fields such as name, description, version, and endpoints. The TypeScript definitions in plugins/codex/scripts/lib/app-server-protocol.d.ts contain the interface definitions for the manifest structure expected by the runtime.

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