OpenCode Plugin Installer

Help users discover, evaluate, and install OpenCode plugins from the community catalog.

1. List Available Plugins

Run the catalog script to see what's available:

python3 ~/.config/opencode/skill/plugin-installer/scripts/list_plugins.py

Output shows name: description with path to detailed file.

2. Read Plugin Details

For relevant matches, read the full plugin file:

references/plugins/<filename>.md

Each file contains:

• Installation config (copy-paste JSON)

• Setup steps

• Features and caveats

• Links to docs

3. Recommend and Install

Show the user:

• What the plugin does

• Install snippet for opencode.json

• Any setup steps (OAuth, config files, etc.)

<question_tool>

Batching: Use the question tool for 2+ related questions. Single questions → plain text.

Syntax: header ≤12 chars, label 1-5 words, add "(Recommended)" to default.

When to ask: Multiple plugins match the need, or plugin has complex setup.

</question_tool>

Installation Format

Add to plugin array in opencode.json:

{ "plugin": [ "package-name@version" ] }

Config locations:

• Global: ~/.config/opencode/opencode.json

• Project: .opencode/opencode.json

Version Pinning

// Pin version (RECOMMENDED) "plugin": ["package@1.2.3"]

// Auto-update on restart "plugin": ["package@latest"]

// Locked to first install (never updates) "plugin": ["package"]

Force update when stuck:

rm -rf ~/.cache/opencode/node_modules ~/.cache/opencode/bun.lock

<documenting_new_plugins>

Adding New Plugins to the Catalog

When you discover a new OpenCode plugin (from web search, GitHub, npm, user mention), you MUST document it for future reference.

Step 1: Gather Plugin Information

Before creating the doc, collect:

Info Where to Find

Package name npm registry, GitHub repo name

Description README, package.json description

Install syntax Check if scoped (@org/pkg ) or plain (pkg )

Version strategy Does it recommend @latest or pinned?

Setup steps OAuth flows, config files, env vars

Provider/model requirements Does it only work with specific providers?

Known issues GitHub issues, compatibility notes

Step 2: Create the Plugin File

Location: ~/.config/opencode/skill/plugin-installer/references/plugins/<name>.md

Naming convention: Use the npm package name with / replaced by - for scoped packages:

• opencode-foo → opencode-foo.md

• @org/opencode-bar → org-opencode-bar.md

Step 3: Use This Template

name: package-name-or-@scope/package-name description: One-line description for catalog listing (max ~80 chars)

Plugin Display Name

Brief description of what this plugin does and why someone would use it.

Installation

```jsonc { "plugin": ["package-name@latest"] } ```

Setup

Prerequisites

• List any requirements (accounts, API keys, other tools)

Configuration

Step-by-step setup instructions.

Features

• Key feature 1
• Key feature 2

Caveats

• Known limitations
• Compatibility notes

Links

• GitHub
• npm

Step 4: Verify the Catalog

After creating, run the listing script to confirm it appears:

python3 ~/.config/opencode/skill/plugin-installer/scripts/list_plugins.py

</documenting_new_plugins>

<frontmatter_requirements>

Field Required Purpose

name

Yes Package name exactly as used in "plugin": []

description

Yes One-liner shown in catalog listings

Important: The name MUST match the npm package name exactly (including scope if any). This is what users will copy into their opencode.json .

</frontmatter_requirements>

Documenting a New Plugin

Say you found @cooldev/opencode-metrics on npm. Create:

File: ~/.config/opencode/skill/plugin-installer/references/plugins/cooldev-opencode-metrics.md

name: @cooldev/opencode-metrics description: Track AI usage metrics and export to dashboards

OpenCode Metrics

Export your OpenCode usage data to external dashboards...

Installation

```jsonc { "plugin": ["@cooldev/opencode-metrics@latest"] } ```

...