AI Runtime Manifest Files in i-have-adhd: Functions of .claude-plugin, .codex-plugin, and opencode.json

The i-have-adhd repository uses distinct JSON manifest files—including .claude-plugin/plugin.json, .codex-plugin/plugin.json, opencode.json, qwen-extension.json, and kimi.plugin.json—to declare plugin metadata, UI configurations, and sandbox permissions for each specific AI runtime.

The ayghri/i-have-adhd project is architected as a cross-platform AI plugin, requiring dedicated configuration files for every supported environment. These AI runtime manifest files act as the single source of truth for Claude Code, Codex, OpenCode, Qwen, and Kimi, instructing each loader how to register the skill, display it to users, and restrict its operational scope.

Claude Code Runtime Manifests

The Claude Code integration relies on two complementary files within the .claude-plugin directory to separate technical metadata from marketplace presentation.

Core Plugin Descriptor (.claude-plugin/plugin.json)

Located at .claude-plugin/plugin.json, this file provides the essential metadata that the Claude Code runtime parses during initialization. It declares the plugin name, version, and a concise description that identifies the skill within the CLI.

According to the source code, the runtime expects this file to contain standard JSON fields that map directly to the plugin registry.

{
  "name": "i-have-adhd",
  "version": "1.0.0",
  "description": "Shape Claude Code output for an ADHD reader."
}

You can view the source file here: [.claude-plugin/plugin.json](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/plugin.json).

Marketplace Metadata (.claude-plugin/marketplace.json)

The second file, .claude-plugin/marketplace.json, supplies the Claude Code marketplace UI with human-readable marketing data. It includes fields for the display name, owner information, and the category under which the plugin is listed, distinct from the technical descriptor used by the loader.

{
  "name": "I Have ADHD",
  "description": "Optimizes Claude's responses for ADHD cognitive styles.",
  "category": "Productivity"
}

Access the full schema here: [.claude-plugin/marketplace.json](https://github.com/ayghri/i-have-adhd/blob/main/.claude-plugin/marketplace.json).

Codex Runtime Manifest (.codex-plugin/plugin.json)

For the Codex runtime, the manifest at .codex-plugin/plugin.json extends beyond basic metadata to include an interface object. This object dictates how Codex renders the plugin in its UI, specifying display names, default prompts, and icon paths.

The following JavaScript snippet demonstrates how a loader might consume this file to extract both core metadata and interface settings:

import fs from 'fs';
import path from 'path';

const manifestPath = path.join('.codex-plugin', 'plugin.json');
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

console.log(`Loading ${manifest.name} v${manifest.version}`);
console.log(`Display Name: ${manifest.interface.display_name}`);
console.log(`Default Prompt: ${manifest.interface.default_prompt}`);

Source reference: [.codex-plugin/plugin.json](https://github.com/ayghri/i-have-adhd/blob/main/.codex-plugin/plugin.json).

OpenCode Runtime Manifest (opencode.json)

The opencode.json file serves as the configuration hub for the OpenCode runtime. Unlike the simpler JSON files used by other runtimes, this manifest defines strict sandbox permissions and LLM model selections.

It explicitly allows read, grep, and glob operations while denying all write access, and it specifies which models to use for default and small-context operations.

{
  "permission": {
    "read": {
      "*": "allow"
    },
    "write": {
      "*": "deny"
    },
    "grep": "allow",
    "glob": "allow"
  },
  "models": {
    "default": "openai/gpt-4o",
    "small": "openai/gpt-4o-mini"
  }
}

A runtime implementation might validate access using a TypeScript utility like this:

import opencodeConfig from './opencode.json';

function canRead(filePath: string): boolean {
  const rules = opencodeConfig.permission.read;
  return rules[filePath] === 'allow' || rules['*'] === 'allow';
}

// Returns true based on the wildcard allow rule
console.log(canRead('/cache/repos/github.com/ayghri/i-have-adhd/main/.codex-plugin/plugin.json'));

View the complete configuration: [opencode.json](https://github.com/ayghri/i-have-adhd/blob/main/opencode.json).

Qwen and Kimi Runtime Manifests

Both the Qwen and Kimi runtimes require dedicated manifests that point to the skills directory while differing slightly in their support for UI metadata.

Qwen Extension Descriptor (qwen-extension.json)

The qwen-extension.json file provides a minimal declaration containing the name, version, description, and the skills path that the Qwen Code runtime loads on startup.

{
  "name": "i-have-adhd",
  "version": "1.0.0",
  "description": "ADHD-optimized output formatting",
  "skills": "./skills"
}

Source: [qwen-extension.json](https://github.com/ayghri/i-have-adhd/blob/main/qwen-extension.json).

Kimi Plugin Descriptor (kimi.plugin.json)

Similarly, kimi.plugin.json supplies the Kimi runtime with name, version, description, and skills location. However, it also includes an interface section to configure the display name and description within Kimi’s native UI.

{
  "name": "i-have-adhd",
  "version": "1.0.0",
  "description": "ADHD-friendly formatting",
  "skills": "./skills",
  "interface": {
    "display_name": "I Have ADHD",
    "description": "Formats responses for ADHD readers"
  }
}

Source: [kimi.plugin.json](https://github.com/ayghri/i-have-adhd/blob/main/kimi.plugin.json).

Generic Fallback Manifest (plugin.json)

At the repository root, a generic plugin.json acts as a fallback for runtimes that do not require runtime-specific schemas. It contains only the most basic fields—name and description—ensuring compatibility with simpler loader implementations.

Source: [plugin.json](https://github.com/ayghri/i-have-adhd/blob/main/plugin.json).

Summary

• .claude-plugin/plugin.json defines core metadata (name, version) for the Claude Code loader.
• .claude-plugin/marketplace.json provides UI-specific marketing data for the Claude marketplace.
• .codex-plugin/plugin.json includes an interface object for rendering UI elements in Codex.
• opencode.json configures sandbox permissions (read/grep/glob allowed, write denied) and model selection for OpenCode.
• qwen-extension.json offers a minimal manifest pointing to the skills directory for Qwen Code.
• kimi.plugin.json serves the same function for Kimi while adding an interface section for display properties.
• plugin.json (root) functions as a generic fallback for basic runtime compatibility.

Frequently Asked Questions

What is the difference between .claude-plugin/plugin.json and marketplace.json?

The plugin.json file contains technical metadata required by the Claude Code runtime to load and identify the plugin, such as its version and internal name. The marketplace.json file is consumed by the user interface layer to display human-readable descriptions, categories, and ownership information in the Claude marketplace.

How does opencode.json restrict plugin permissions?

The opencode.json manifest uses a structured permission object to enforce a security sandbox. It explicitly sets "allow" for read, grep, and glob operations across all paths, while setting "deny" for all write operations, preventing the plugin from modifying the filesystem.

Do I need a separate manifest for every AI runtime?

Yes, each supported runtime expects a specific file name and schema. Claude Code looks for .claude-plugin/plugin.json, Codex expects .codex-plugin/plugin.json, OpenCode requires opencode.json, Qwen uses qwen-extension.json, and Kimi relies on kimi.plugin.json to properly initialize the plugin.

What happens if a runtime cannot find its specific manifest file?

If a runtime-specific manifest is missing, the loader may fall back to the generic plugin.json located in the repository root. This file provides only basic name and description fields, which is sufficient for runtimes with minimal configuration requirements but may lack advanced features like UI customization or sandbox rules.

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