How Claude Code and Codex Marketplace Manifests Power the i‑have‑adhd Plugin

Claude Code and Codex marketplace manifests provide JSON-based metadata that enables runtime discovery, validation, and UI rendering for the i‑have‑adhd plugin across both AI coding platforms.

The i‑have‑adhd repository implements a dual-manifest architecture to support plugin distribution in both the Claude Code and Codex marketplaces. These manifest files act as the single source of truth for how each runtime identifies, describes, and loads the ADHD-optimized productivity plugin.

Claude Code Manifest Structure

The Claude Code marketplace uses two separate JSON files to separate runtime metadata from marketplace presentation.

Plugin Descriptor: .claude-plugin/plugin.json

Located at [/.claude-plugin/plugin.json](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json), this file supplies the minimal metadata required by the Claude Code runtime:

• name – Machine-readable identifier
• version – Semantic version string
• description – Human-readable summary
• author – Plugin creator attribution

The Claude Code runtime validates these four fields during startup. Missing or malformed data prevents plugin registration.

Marketplace Entry: .claude-plugin/marketplace.json

The [/.claude-plugin/marketplace.json](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) file conforms to the Claude Code Marketplace schema and controls how the plugin appears in the marketplace UI:

{
  "name": "i-have-adhd",
  "description": "ADHD-friendly productivity assistant",
  "owner": "ayghri",
  "category": "productivity",
  "source": "./"
}

The source field ("./") points to the repository root, telling the runtime where to load plugin code. The category field ("productivity") determines browse placement in the marketplace interface.

Codex Manifest Structure

Codex consolidates metadata into a single, richer descriptor that includes UI-specific configuration.

Full Plugin Definition: .codex-plugin/plugin.json

The [/.codex-plugin/plugin.json](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) file extends beyond basic metadata to define the complete marketplace experience:

{
  "version": "1.0.0",
  "description": "ADHD-friendly productivity assistant for developers",
  "author": "ayghri",
  "homepage": "https://github.com/ayghri/i-have-adhd",
  "repository": "https://github.com/ayghri/i-have-adhd",
  "license": "MIT",
  "skills": "./skills/",
  "interface": {
    "displayName": "I Have ADHD",
    "shortDescription": "Stay focused with ADHD-optimized guidance",
    "icons": { "light": "./assets/icon-light.svg", "dark": "./assets/icon-dark.svg" },
    "brandColor": "#FF6B35",
    "capabilities": ["productivity", "focus", "task-management"],
    "defaultPrompt": "You are an ADHD-friendly assistant..."
  }
}

The interface object is unique to Codex and drives visual rendering:

• displayName – Marketplace title shown to users
• brandColor – Hex color for consistent branding
• icons – Theme-responsive icon paths
• capabilities – Feature tags for filtering and search
• defaultPrompt – System prompt injected on plugin selection

How the Manifests Function at Runtime

Discovery Phase

When Claude Code or Codex initializes, each runtime scans for hidden plugin directories:

• Claude Code: .claude-plugin/
• Codex: .codex-plugin/

Both runtimes expect plugin.json as the entry point. Codex additionally validates against its extended schema, rejecting files missing required interface fields.

Skill Loading

Codex's manifest specifies skill locations via the skills field ("./skills/"). The runtime loads skill definitions from this path, particularly [skills/i-have-adhd/SKILL.md](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md), which contains the behavioral rules that shape ADHD-friendly output formatting.

Execution Flow

Once validated, the runtime:

1. Bundles plugin source files referenced in source (Claude Code) or skills (Codex)
2. Registers the marketplace entry using UI metadata from marketplace.json or interface
3. Routes user requests through the plugin's skill logic on activation

Programmatic Manifest Access

These Node.js examples demonstrate how to read and process manifest data for testing or tooling:

// Read Claude Code marketplace metadata
import fs from 'fs';

const claudeMarketplace = JSON.parse(
  fs.readFileSync('.claude-plugin/marketplace.json', 'utf8')
);

console.log('Plugin category:', claudeMarketplace.category);
console.log('Source path:', claudeMarketplace.source);

// Extract Codex UI configuration for rendering
import fs from 'fs';

const codexPlugin = JSON.parse(
  fs.readFileSync('.codex-plugin/plugin.json', 'utf8')
);

const { displayName, brandColor, icons } = codexPlugin.interface;

console.log(`${displayName} uses brand color ${brandColor}`);
console.log('Light theme icon:', icons.light);

Both manifests are plain JSON—no build step required—making them directly consumable by any tooling that needs plugin metadata.

Key File Reference

File	Runtime	Purpose
.claude-plugin/plugin.json	Claude Code	Minimal runtime metadata
.claude-plugin/marketplace.json	Claude Code	Marketplace UI registration
.codex-plugin/plugin.json	Codex	Full plugin + UI definition
skills/i-have-adhd/SKILL.md	Codex	Behavioral skill rules

Summary

• Claude Code splits manifest responsibilities across plugin.json (runtime) and marketplace.json (UI), using a minimal four-field schema for validation as implemented in ayghri/i-have-adhd.
• Codex unifies configuration in plugin.json with an extended interface object controlling visual presentation, including displayName, brandColor, and defaultPrompt.
• The source field (Claude Code) and skills field (Codex) determine where each runtime loads executable code.
• Both marketplaces discover plugins through convention-based hidden directories scanned at startup.

Frequently Asked Questions

What happens if a manifest file is missing a required field?

The runtime rejects the plugin during validation. Claude Code requires name, version, description, and author in plugin.json. Codex additionally requires the interface object with displayName, shortDescription, and defaultPrompt. Missing data prevents marketplace registration.

Can one repository support both Claude Code and Codex simultaneously?

Yes. The i-have-adhd repository demonstrates this by maintaining separate .claude-plugin/ and .codex-plugin/ directories. Each runtime only scans its designated folder, so conflicts do not occur.

How does the defaultPrompt in Codex manifests affect behavior?

The defaultPrompt string becomes the system prompt injected when a user activates the plugin from the marketplace. For i-have-adhd, this establishes the ADHD-optimized response style before any user messages are processed.

Where are skill files located relative to the Codex manifest?

The skills field in .codex-plugin/plugin.json specifies a relative path—"./skills/" in this repository. The runtime resolves this against the repository root and loads all SKILL.md files found within that directory tree.

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