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

> Learn how Claude Code and Codex marketplace manifests enable runtime discovery, validation, and UI rendering for the i-have-adhd plugin on AI coding platforms.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json)

Located at [[`/.claude-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main//.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`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json)

The [[`/.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main//.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](https://www.schemastore.org/claude-code-marketplace.json) and controls how the plugin appears in the marketplace UI:

```json
{
  "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`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json)

The [[`/.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main//.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:

```json
{
  "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`](https://github.com/ayghri/i-have-adhd/blob/main/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)](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`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```javascript
// 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);

```

```javascript
// 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`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json) | Claude Code | Minimal runtime metadata |
| [`.claude-plugin/marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json) | Claude Code | Marketplace UI registration |
| [`.codex-plugin/plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json) | Codex | Full plugin + UI definition |
| [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | Codex | Behavioral skill rules |

## Summary

- **Claude Code** splits manifest responsibilities across [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json) (runtime) and [`marketplace.json`](https://github.com/ayghri/i-have-adhd/blob/main/marketplace.json) (UI), using a minimal four-field schema for validation as implemented in ayghri/i-have-adhd.
- **Codex** unifies configuration in [`plugin.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/.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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) files found within that directory tree.