install-plugin-to-socket

Install Plugin To Socket

Wire an in-development Codex plugin into Codex's documented local plugin surfaces.

This skill is for local Codex plugin development workflows. It does not publish plugins, does not manage the official plugin directory, and does not claim undocumented control over Codex's installed-plugin cache internals.

Inputs

Required: source plugin directory
- for mutating actions, this must be the plugin root containing .codex-plugin/plugin.json
- verify may also accept a repo root that contains exactly one staged plugin under plugins/ or exactly one marketplace-resolved plugin root
Optional: scope
- default: personal
- repo
- personal
Optional: config path override
- --config <path>
- when omitted, resolve defaults from:
  - .codex/profiles/install-plugin-to-socket/customization.yaml
  - ~/.config/gaelic-ghost/agent-plugin-skills/install-plugin-to-socket/customization.yaml
Optional: target repo root when scope=repo
- default: current working directory when the helper is run from the target repo
Optional: action
- install
- update
- uninstall
- verify
- repair
- enable
- disable
- promote
Optional: install mode
- default: copy
- copy
- symlink
Optional: Codex config path override
- --codex-config-path <path>
Optional: whether the request is check-only planning or real apply behavior

Workflow

Confirm the task is local Codex plugin wiring, not generic plugin authoring or metadata review.
Resolve the effective source plugin root and read the plugin manifest at .codex-plugin/plugin.json.
- Keep repo-root source auto-detection as a verify-only convenience.
- For install, update, uninstall, repair, enable, disable, and promote, require the canonical plugin root directly.
Infer the plugin name, version, description, interface metadata, and optional plugin surfaces from that manifest.
Use scripts/install_plugin_to_socket.py in check-only mode first.
Resolve the effective install scope in this order:
- explicit --scope
- explicit --config
- repo profile
- global profile
- built-in default personal
For personal scope, target:
- ~/.codex/plugins/<plugin-name>
- ~/.agents/plugins/marketplace.json
For repo scope, target:
- $REPO_ROOT/plugins/<plugin-name>
- $REPO_ROOT/.agents/plugins/marketplace.json
Keep marketplace source.path relative to the marketplace root, prefixed with ./, and inside that root.
Merge one plugin entry into the marketplace without overwriting unrelated entries.
Default to the documented Codex local-plugin flow:
- stage the plugin at the repo or personal plugin path
- point the marketplace entry at that staged path
- for personal-scope install, also write the plugin enabled state to ~/.codex/config.toml with enabled = true
Use copy mode as the default because it matches the current OpenAI examples for local plugin installs and gives Codex a stable staged plugin tree to recache from.
Treat update as the update workflow when the source clone is ahead of the staged install copy. It should recopy the source plugin tree into the staged path and rewrite the marketplace entry if needed.
Treat verify as the audit-oriented workflow for checking whether the staged plugin tree, marketplace entry, optional plugin surfaces, and config-state expectations still match the source plugin.
Treat repair as the bounded repair workflow when the intended staged plugin should keep its current scope, but the local install surface drifted. In repo scope, it may also normalize the common legacy case where the repo's own plugin marketplace entry still points at ./ instead of ./plugins/<plugin-name>.
Treat enable and disable as explicit Codex config-state workflows backed by ~/.codex/config.toml entries in the form [plugins."plugin-name@marketplace-name"].
Treat promote as the bounded workflow that copies the source plugin into personal scope, writes the personal marketplace entry, carries forward the repo install's enabled-state if present, and then removes the repo-local install surface.
Treat symlink mode as an advanced local-dev override only when a maintainer explicitly wants a staged in-scope symlink instead of the documented copied tree.
For install, update, and repair, materialize the staged plugin path in the chosen mode and update the marketplace entry.
For personal-scope install, enable the plugin by default in ~/.codex/config.toml after wiring the staged plugin tree and marketplace entry.
For uninstall, remove only the matching marketplace entry, staged plugin path, and matching plugin config-state entry for that install target.
After apply behavior, tell the maintainer to restart Codex and verify that the plugin appears in the plugin directory or reflects the intended enabled-state.

Usage Examples

Personal install:
- uv run python skills/install-plugin-to-socket/scripts/install_plugin_to_socket.py --source-plugin-root plugins/agent-plugin-skills --action install --run-mode apply
- this now enables the personal-scope plugin by default in ~/.codex/config.toml
Repo-local install:
- uv run python skills/install-plugin-to-socket/scripts/install_plugin_to_socket.py --source-plugin-root /path/to/plugin --scope repo --repo-root /path/to/target-repo --action install --run-mode apply
Update a staged copied install after source changes:
- uv run python skills/install-plugin-to-socket/scripts/install_plugin_to_socket.py --source-plugin-root /path/to/plugin --action update --run-mode apply
Remove a local install cleanly:
- uv run python skills/install-plugin-to-socket/scripts/install_plugin_to_socket.py --source-plugin-root /path/to/plugin --action uninstall --run-mode apply
Verify an already wired install without mutating it:
- uv run python skills/install-plugin-to-socket/scripts/install_plugin_to_socket.py --source-plugin-root /path/to/plugin --action verify --run-mode check-only --print-md
Repair a drifted install surface in one pass:
- uv run python skills/install-plugin-to-socket/scripts/install_plugin_to_socket.py --source-plugin-root /path/to/plugin --scope repo --repo-root /path/to/target-repo --action repair --run-mode apply
Enable or disable a wired plugin in Codex config:
- uv run python skills/install-plugin-to-socket/scripts/install_plugin_to_socket.py --source-plugin-root /path/to/plugin --action enable --run-mode apply
- uv run python skills/install-plugin-to-socket/scripts/install_plugin_to_socket.py --source-plugin-root /path/to/plugin --action disable --run-mode apply
Promote a repo-local install into personal scope:
- uv run python skills/install-plugin-to-socket/scripts/install_plugin_to_socket.py --source-plugin-root /path/to/plugin --scope repo --repo-root /path/to/target-repo --action promote --run-mode apply

Repairing Drifted Installs

Use this skill as the repair surface for bad or stale local Codex plugin installs.

Common repair cases:

missing-target-plugin-root
- The marketplace entry exists, but the staged plugin path is missing.
- Fix: rerun install in the intended mode.
missing-marketplace-entry
- The staged plugin path exists, but the marketplace does not expose it.
- Fix: rerun install in the intended mode.
stale-marketplace-entry
- The marketplace entry points at the wrong staged path or has stale metadata.
- Fix: rerun update in the intended mode.
stale-target-materialization
- The staged plugin path is present, but its materialization does not match the requested mode.
- Fix: rerun update with the intended copy or symlink mode.
stale-target-copy
- The staged plugin tree is a copied install, but its contents no longer match the current source plugin tree.
- Fix: rerun update in copy mode so the staged Codex install path is updated from the source clone.
invalid-marketplace-entry-empty-relative-source-path
- A repo-local marketplace entry points at ./, which Codex may reject for the whole marketplace.
- Fix: run repair in repo scope so the repo's own plugin is restaged under plugins/<plugin-name>/ and the marketplace entry is rewritten to that staged path.
missing-plugin-enabled-state
- Codex config does not include an explicit enabled-state entry for the plugin key.
- Fix: rerun install for a missing personal install default-enable, or rerun enable / disable when the intended state differs.
stale-plugin-enabled-state
- Codex config includes a plugin entry, but the enabled-state does not match the requested workflow.
- Fix: rerun enable or disable, depending on the intended state.
missing-mcp-surface, missing-app-surface, missing-hooks-config, missing-interface-asset
- The source plugin manifest or optional plugin packaging surfaces are incomplete.
- Fix: repair the plugin packaging before trusting the staged local install.

Preferred repair flow:

Run the helper in check-only mode first.
Confirm the intended scope and install mode.
Use update when the staged path and marketplace entry should continue to exist but need to be rewritten.
Use repair when the drift includes invalid repo-local marketplace wiring, a missing staged plugin root, or a legacy repo-root plugin entry that should be normalized to plugins/<plugin-name>/.
Use install when a new personal install should take the default enabled path, and use enable or disable when marketplace wiring is correct but Codex config-state needs an explicit follow-up change.
Use promote when a repo-local install should become the personal default install surface instead.
Use uninstall and then install when the staged path belongs to the wrong source plugin, the wrong scope, or the wrong plugin name.
Restart Codex after the repair so the local marketplace view and installed cache pick up the staged plugin changes.

Troubleshooting

If a repo-local plugin still does not show up after install, update, or repair, fully restart Codex in that repo. A live workspace can continue using the marketplace view it loaded before the install surface changed.
If /plugins still looks wrong after restart, check ~/.codex/log/codex-tui.log for marketplace warnings such as skipping marketplace or local plugin source path must not be empty.
Repo-local plugin visibility is scoped to the repo that owns .agents/plugins/marketplace.json. Use personal scope when the same plugin should be broadly available across repos.
The /plugins slash command ordering may not be intuitive or obviously alphabetical, so scan the full list before concluding a plugin is missing.

Remaining Gaps

This skill now manages Codex plugin enable or disable state through ~/.codex/config.toml, but it does not try to manage project-scoped .codex/config.toml overrides.
The current overwrite policy still uses replace-in-place semantics for staged targets; backup and fail-on-existing variants remain planned work.

Output Contract

Return a short summary plus JSON with:
- run_context
  - include config resolution context such as config_path and scope_source
- scope
- action
- install_mode
- source_plugin
- target_plugin_root
- marketplace_path
- codex_config_path
- plugin_config_key
- findings
- apply_actions
- restart_required
- verification_steps
- errors
If there are no findings, no apply actions, and no errors, output exactly No findings.

Guardrails

Never overwrite an existing marketplace catalog wholesale.
Never point source.path outside the marketplace root.
Never point a repo marketplace directly at an adjacent plugin repo outside the chosen marketplace root; use a staged copy or a staged symlink path inside the scope root instead.
Never delete the source plugin repo during uninstall; only remove the staged install target path.
Never claim that updating the marketplace file alone installs a plugin into undocumented Codex internals.
Never use this skill to publish a plugin publicly.
Never touch Claude plugin wiring here; this skill is for Codex local plugin development surfaces.

References

references/customization-schema.md
references/local-plugin-install-notes.md