plugin-creator

Source excerpt starting at line 1.

1# Updating Existing Local Plugins2 3Use this reference when a plugin already exists and the request is about updating the plugin during 4local development.5 6All scripts here are specified relative to the skill root. Update the path for running the scripts7depending on your current working directory.8 9## When To Use This Flow10 11Use this flow when all of the following are true:12 13- the plugin already exists locally14- the marketplace entry already points at the plugin source you are editing15- the user wants Codex to see the updated plugin without manually editing marketplace files16 17If the user still needs the initial plugin entry or marketplace structure created, use the scaffold18flow first and only then switch to this reinstall flow.19 20## Update Loop21 221. Before changing the plugin, read the marketplace name from the personal marketplace file:23 24```bash25python3 scripts/read_marketplace_name.py26```27 28Here, "personal marketplace" means the marketplace whose file is at29`~/.agents/plugins/marketplace.json`. On Windows, use the equivalent path under the user profile.30The helper uses Python's home-directory resolution and prints the validated marketplace name to use31when constructing the install command. If the helper fails, stop.32 33To read the name from a different marketplace file, pass the path directly:34 35```bash36python3 scripts/read_marketplace_name.py --marketplace-path <path-to-marketplace.json>37```38 392. Update the plugin manifest to a single Codex cachebuster suffix:40 41```bash42python3 scripts/update_plugin_cachebuster.py \43  <plugin-path>44```45 46The helper validates the plugin name before changing the manifest. If validation fails, stop.47Prefer the default helper behavior here. If you omit `--cachebuster`, the helper uses a UTC48timestamp down to seconds, which is the recommended path for routine local iteration.49 50Only use a manual cachebuster override when the user explicitly asks for one or when a workflow51outside Codex depends on a specific token:52 53```bash54python3 scripts/update_plugin_cachebuster.py \55  <plugin-path> \56  --cachebuster local-20260519-18451657```58 593. Reinstall from that marketplace name:60 61```bash62codex plugin add <plugin-name>@<marketplace-name-from-marketplace-json>63```64 65The default personal marketplace is discovered implicitly from66`~/.agents/plugins/marketplace.json`. You do not need `codex plugin marketplace add` for that67path, and `codex plugin marketplace list` is not the right check for whether that default68marketplace exists.69 704. If the plugin is not using the personal marketplace file, check which configured local71   marketplace is actually surfacing that plugin:72 73```bash74codex plugin list75```76 77If the plugin is not in the personal marketplace file, confirm which marketplace entry points at78the plugin source you are editing and make sure that marketplace is still local. If it is a79different local marketplace, reinstall from that marketplace name instead of forcing the personal80marketplace flow. If it is not local, stop and help the user resolve the mismatch before81continuing.82 835. If the plugin lives in a different confirmed local marketplace, substitute that marketplace84   name:85 86```bash87codex plugin add <plugin-name>@<local-marketplace>88```89 906. Prompt the user to use a new thread to try the updated plugin, so that Codex picks up new skills91   and tools.92 93## Cachebuster Policy94 95- Preserve the existing version prefix and replace only the suffix.96- Treat the preserved prefix as everything before `+`.97- Use the format:98 99```text100<base-version>+codex.<cachebuster>101```102 103Examples:104 105- `0.1.0` → `0.1.0+codex.local-20260519-184516`106- `0.1.0+codex.old-token` → `0.1.0+codex.local-20260519-184516`107- `1.2.3-beta.1+codex.prev` → `1.2.3-beta.1+codex.local-20260519-184516`108- `dev-build+other-tag` → `dev-build+codex.local-20260519-184516`109 110Replace the existing Codex cachebuster instead of appending another one. Do not keep incrementing111numeric version components just to trigger reinstall behavior.112 113## Marketplace Rules114 115- Marketplace manipulation should happen through commands, not by hand-editing `marketplace.json`116  or `config.toml` during this update/reinstall flow.117- Prefer the personal marketplace file for the default scaffolded flow.118- Read the personal marketplace name with119  `python3 scripts/read_marketplace_name.py` and use the printed value when constructing120  `codex plugin add <plugin-name>@<marketplace-name>`.121- For non-default marketplace files, use122  `python3 scripts/read_marketplace_name.py --marketplace-path <path-to-marketplace.json>` to read123  the name before constructing reinstall commands.124- Do not tell the user to run `codex plugin marketplace add` for the default personal-marketplace125  flow. That marketplace is discovered implicitly by Codex.126- If the user specified a different marketplace path, make sure that marketplace is installed127  before giving install or reinstall instructions. Non-default marketplace paths are not128  discovered implicitly.129- Use `codex plugin list` when the plugin lives in a different configured marketplace and you need130  to confirm which marketplace is surfacing that plugin.131- If a non-default local marketplace has not been configured yet, install it with132  `codex plugin marketplace add <path-to-marketplace-root>` before telling the user to run133  `codex plugin add <plugin-name>@<marketplace-name>`.134- If the plugin is not in the personal marketplace file, confirm that the selected marketplace is135  local before telling the user to reinstall from it.136- If the selected marketplace is not local, stop and help the user resolve that mismatch rather137  than pretending the normal local reinstall flow applies.138- If the plugin source is not already the source referenced by the chosen marketplace entry, stop139  and fix that first. This update flow does not rewrite marketplace entries.140 141## After Reinstall142 143After reinstalling, prompt the user to start a new thread for testing. That is the safe boundary for144picking up the updated plugin and its MCP tools.145