plugin-updater

Plugin lifecycle manager for OpenCode and Claude Code launchers. Handles install, update, rebuild, downgrade, and uninstall operations for all plugins.

Under-the-Hood Architecture

flowchart TD
    %% Triggers
    subgraph Execution_Triggers [Execution Triggers]
        CLI_BOOT[CLI Startup (claude/oc)]
        TUI_MENU[Launcher TUI Actions]

        CLI_BOOT -->|Auto-runs hook on start| UPDATER_CORE
        TUI_MENU -->|Manual rebuild/downgrade/uninstall| UPDATER_CORE
    end

    %% Core Logic
    subgraph Plugin_Updater [Updater Core Logic]
        UPDATER_CORE[Updater Engine]
        API_LAYER[global.OpenCodeAPI Interop]
        GIT_MGR[Git Operations Manager]
        DEPLOYER[Plugin Deployer]

        UPDATER_CORE <-->|Requests repo paths| API_LAYER
        UPDATER_CORE -->|Trigger sync| GIT_MGR
        UPDATER_CORE -->|Trigger deploy| DEPLOYER
    end

    %% External & Storage
    subgraph Storage_and_Network [Storage & External]
        GH_REPOS[GitHub (intisy-ai/plugin-*)]
        LOCAL_WORKSPACE[(.config/github/repos/intisy-ai/)]
        CC_PLUGINS[(.claude/plugin/)]
        OC_PLUGINS[(.config/opencode/plugin/)]

        GIT_MGR <-->|git clone/pull| GH_REPOS
        GIT_MGR -->|Updates source| LOCAL_WORKSPACE
        DEPLOYER -->|Copies compiled output| CC_PLUGINS
        DEPLOYER -->|Copies compiled output| OC_PLUGINS
    end

Loading

Structure

• src/
  • TypeScript source (index engine + git, npm, deploy, config, log, env, syncbridge, cli, commands).
• dist/
  • dist/index.js — plugin entry + the node … config CLI; dist/cli.js — the plugin-updater bin.

Installation

Via plugin-updater (recommended)

npx plugin-updater@latest init https://github.com/intisy-ai/plugin-updater

Via npm

npm install plugin-updater

Adding plugins

plugin-updater is the one plugin added directly to OpenCode's opencode.jsonc (every other plugin goes through plugins.json); the loaders also resolve and run it on startup. To register a plugin from the CLI:

plugin-updater add https://github.com/intisy-ai/<plugin>      # register a git plugin
plugin-updater add https://github.com/intisy-ai/<plugin> --sync  # …and mirror it to the other app

Cross-app plugin sync (sync: true)

A plugins.json entry flagged sync: true is mirrored into the other app's plugins.json, so a plugin enabled in OpenCode is also installed in Claude Code (and vice versa). At the start of earlyLaunch, plugin-updater loads sync-bridge's library bundle (dist/lib.js) and calls syncPlugins(), then re-reads the list so a freshly-synced-in plugin is cloned and built in the same launch. It is additive (never removes) and a no-op when sync-bridge isn't installed.

{ "name": "antigravity-auth", "url": "https://github.com/intisy-ai/antigravity-auth", "enabled": true, "autoUpdate": false, "sync": true }

Set it from the CLI with --sync:

plugin-updater add https://github.com/intisy-ai/antigravity-auth --sync

API

Method	Description
rebuild(pluginItem)	Pull latest and redeploy
downgrade(pluginItem, commitHash)	Checkout specific commit
disable(pluginItem)	Cleanup on disable
uninstall(pluginItem)	Remove repo and deployed files
registerTests(testApi)	Register sync verification tests

Configuration

Config file: <configDir>/config/plugin-updater.json (edit via the loader or /plugin-updater-config set).

{
  "logging": true,
  "default_update_interval_hours": 1,
  "git_timeout_seconds": 120,
  "npm_timeout_seconds": 300,
  "build_timeout_seconds": 300,
  "daemon_health_timeout_ms": 1500,
  "self_update": true,
  "update_on_launch": true
}

Key	Default
logging	true
default_update_interval_hours	1
git_timeout_seconds	120
npm_timeout_seconds	300
build_timeout_seconds	300
daemon_health_timeout_ms	1500
self_update	true
update_on_launch	true

Commands

Command	Description	Arguments
/plugin-updater-config	View/change plugin-updater configuration	`list
/config	View/change ANY plugin's settings and the global settings	`[global

Dependencies

• core
• sync-bridge

Logging

Logs are written to <configDir>/logs/YYYY-MM-DD/plugin-updater-HH-MM-SS.log and are toggled by this plugin's logging config (default on). Console mirroring is global, off by default, and controlled by the shared config/settings.json logConsole flag.

License

MIT.