Skip to content

feat(sync): zero-touch auto-install codex plugins for team distribution#55

Merged
em0t merged 1 commit intomainfrom
feat/codex-auto-install
Apr 21, 2026
Merged

feat(sync): zero-touch auto-install codex plugins for team distribution#55
em0t merged 1 commit intomainfrom
feat/codex-auto-install

Conversation

@em0t
Copy link
Copy Markdown
Collaborator

@em0t em0t commented Apr 21, 2026

Summary

  • Add Step 3 to ensure-codex-plugins.sh: copy enabled *@taptap-plugins from the marketplace clone (~/.codex/.tmp/marketplaces/taptap-plugins/) into ~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/. This is the equivalent of the TUI "Install plugin" action.
  • Auto-enable any plugin marked INSTALLED_BY_DEFAULT in marketplace.json (currently git and sync) unless the user explicitly set enabled = false.
  • Together with the existing project-mirror step, the SessionStart hook now takes a fresh team member from "nothing" to "git/sync registered, enabled, and installed in cache" with zero TUI clicks.

Motivation

Codex 0.121.0 git-source marketplaces require manual TUI confirmation per plugin even with INSTALLED_BY_DEFAULT policy — only local-source marketplaces auto-install at codex marketplace add time. That breaks team distribution: every new member would have to remember to open Codex TUI, navigate to the plugin picker, and click install before git@taptap-plugins and sync@taptap-plugins appear in $git/$sync skill pickers.

Reverse engineering of Codex 0.121.0+:

  • Plugin install state is no longer tracked in ~/.codex/plugins/installed_plugins.json (the file is preserved but unused). Codex now derives "installed" state from the existence of ~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/.codex-plugin/plugin.json.
  • The TUI Install plugin button just copies the source directory from the marketplace clone into that cache path.
  • We can replicate that copy from the SessionStart hook, eliminating the manual click.

Scope

  • GitHub workflows / repository automation
  • Marketplace metadata or release flow
  • Plugin implementation
  • Tests or validation scripts
  • Documentation

Validation

  • Local verification completed
  • CI validation expected to pass
  • No runtime verification needed

End-to-end on the author's machine:

  1. Wiped ~/.codex/plugins/cache/taptap-plugins/, removed [marketplaces.taptap-plugins] and [plugins."*@taptap-plugins"] segments from ~/.codex/config.toml, deleted ~/.codex/.tmp/marketplaces/taptap-plugins/ and the sync marker.
  2. Ran bash plugins/sync/scripts/ensure-codex-plugins.sh once → log:
    ℹ️  marketplace taptap-plugins 未注册,运行 codex marketplace add taptap/agents-plugins
    ✅ 已注册 marketplace taptap-plugins
    ✅ 默认 enable INSTALLED_BY_DEFAULT 插件: git@taptap-plugins, sync@taptap-plugins
    ✅ 已 install 到 cache: git@0.1.16, sync@0.1.28
    ✅ Codex 插件配置已就绪:marketplace=taptap-plugins
    
  3. Confirmed ~/.codex/plugins/cache/taptap-plugins/{git/0.1.16,sync/0.1.28}/.codex-plugin/plugin.json exists.
  4. Confirmed second run is idempotent ("cache 中已存在,跳过").

tests/validate.sh passes (no test schema change in this PR; existing four cases for the script still cover the marketplace-add and mirror behavior).

Regression Risk

  • ~/.codex/.tmp/marketplaces/<name>/ clone path coupling: if Codex moves the clone location in a future release, Step 3 silently degrades to "marketplace clone not found, skip auto-install" without aborting. Marketplace add and project-mirror still work; users would just need to install via TUI as before.
  • Cache GC: this PR does not delete old version subdirectories (e.g. git/0.1.10/ lingers when git/0.1.16/ is installed). Codex itself should clean these; revisit if disk usage becomes an issue.
  • enabled = false is preserved: if a user explicitly disables a plugin, Step 3 will not re-enable it on subsequent runs (only initial INSTALLED_BY_DEFAULT opt-in writes the true segment).

AI Disclosure

  • Authoring tools: Claude Code (Opus 4.7, 1M context)
  • Review tools: Claude Code (Opus 4.7) — single-pass review of committed diff against the project checklist; no blocking findings

Checklist

  • The PR title is in English
  • Commit messages are in English
  • I updated docs when behavior or workflow changed
  • I considered versioning rules if plugin files changed

Codex 0.121.0 git-source marketplaces require a manual TUI "Install
plugin" click for each plugin — even with `INSTALLED_BY_DEFAULT` policy.
That breaks team distribution: every new member must remember to open
the TUI and click install before plugins appear in `$git`/`$sync` pickers.

Add Step 3 to ensure-codex-plugins.sh that performs the equivalent of
the TUI install:

1. Read the marketplace clone fetched by `codex marketplace add`
   (`~/.codex/.tmp/marketplaces/taptap-plugins/.agents/plugins/marketplace.json`).
2. Auto-enable any plugin marked `INSTALLED_BY_DEFAULT` in the
   marketplace manifest, unless the user has explicitly set `enabled = false`.
3. For every enabled `*@taptap-plugins` not yet in cache, copy
   `<clone>/<source.path>/` → `~/.codex/plugins/cache/taptap-plugins/<name>/<version>/`.

Codex 0.121.0+ derives plugin install state from cache directory
existence; `installed_plugins.json` is no longer used. Documented in
the script header.

Result: SessionStart hook → marketplace registered → plugins enabled →
plugins installed end-to-end with zero TUI interaction.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added scope:docs Changes documentation or contributor guidance. scope:plugins Changes one or more plugins. scope:sync Touches the sync plugin. kind:feature Adds a feature or expands behavior. size:m Medium PR. and removed scope:plugins Changes one or more plugins. scope:docs Changes documentation or contributor guidance. labels Apr 21, 2026
@em0t em0t merged commit b218b56 into main Apr 21, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind:feature Adds a feature or expands behavior. scope:sync Touches the sync plugin. size:m Medium PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant