---
name: pluginstaller
description: Add a Codex plugin from a GitHub repo to a repo or personal marketplace using the current Codex plugin layout and marketplace metadata.
---

# Pluginstaller

Use when the user gives a GitHub repo for a Codex plugin and wants it available in Codex.

Follow the current Codex plugin docs. Do not invent alternate install flows.

## Inputs

- GitHub repo URL or `owner/repo`
- Install scope: `repo` or `personal`
- If the repo contains more than one plugin root, ask which plugin folder to install.

## Workflow

0. If the user does not specify whether the plugin should be repo-scoped or personal, stop and ask.
1. Fetch the repo and locate the plugin root by finding `.codex-plugin/plugin.json`.
2. Read `.codex-plugin/plugin.json` and validate the canonical structure:
   - `name`, `version`, and `description` should exist.
   - Bundled paths such as `skills`, `apps`, and `mcpServers` should be relative to the plugin root and start with `./`.
   - Only `plugin.json` should live inside `.codex-plugin/`.
3. Prefer the built-in `@plugin-creator` skill when the task is to scaffold a new local plugin or add an existing local plugin to a marketplace. Use the manual path below when you are wiring up a repo the user already provided.
4. Copy the entire plugin directory, not just `SKILL.md`, into a marketplace-visible location. Default to the documented standard locations unless the repo already uses a different valid marketplace-relative path:
   - `repo`: `$CWD/plugins/<plugin-name>` and `$CWD/.agents/plugins/marketplace.json`
   - `personal`: `~/.codex/plugins/<plugin-name>` and `~/.agents/plugins/marketplace.json`
5. Preserve the full bundle at the plugin root, including sibling `skills/`, `.app.json`, `.mcp.json`, `assets/`, and any other plugin files. Do not move those files under `.codex-plugin/`.
6. Create or update the marketplace file with the documented schema:
   - top-level marketplace `name`
   - optional `interface.displayName`
   - plugin entry `name`
   - `source.source = "local"`
   - `source.path` relative to the marketplace root:
     - `repo`: `./plugins/<plugin-name>`
     - `personal`: `./.codex/plugins/<plugin-name>`
   - `policy.installation`
   - `policy.authentication`
   - `category`
7. Use marketplace values that match the docs unless the user says otherwise:
   - `policy.installation = "AVAILABLE"`
   - `policy.authentication = "ON_INSTALL"`
   - `category` from `interface.category` when present, otherwise `Productivity`
8. Merge into any existing marketplace file instead of replacing it.
9. Restart Codex and verify the plugin appears in `/plugins`.
10. Report the runtime behavior accurately:
   - The marketplace entry points to the source plugin directory.
   - Codex installs the plugin into `~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/`.
   - For local plugins, the installed cache version is `local`.
   - Plugin enabled or disabled state is stored in `~/.codex/config.toml`.

## Rules

- Prefer the terms `repo marketplace` and `personal marketplace` over `workspace` and `global`.
- Do not present copying into `plugins/` as the complete install. The marketplace entry is what makes the plugin discoverable in Codex.
- Do not flatten or rename the plugin bundle.
- Keep the plugin `name` stable and consistent across folder, manifest, and marketplace entry.
- Keep manifest and marketplace paths relative and `./`-prefixed where the docs require it.
- Treat the documented repo and personal plugin directories as defaults, not absolute requirements, as long as the marketplace `source.path` remains valid and stays inside the marketplace root.
- If the repo already ships a marketplace file, prefer it as the source of truth for marketplace ordering and metadata, and only add or update the plugin entry that is needed.
- If the manifest is missing required basics or uses invalid root-relative paths, fix the plugin structure before claiming installation is complete.

## Scope guide

Use `repo` when the plugin should live with one repo or be shared through that repo's marketplace. Use `personal` when the plugin should be available from the user's own Codex setup across projects.